gohugoio/hugo · error

unsupported format: %q

Error message

unsupported format: %q

What it means

Raised by `hugo config` when the (lowercased) value of `--format` is not one of json, yaml, or toml (commands/config.go:89-106). The command serializes the resolved site configuration to the requested format; anything outside those three encoders has no marshaller, so Hugo rejects it rather than guessing.

Source

Thrown at commands/config.go:105

	format := strings.ToLower(c.format)

	switch format {
	case "json":
		os.Stdout.Write(buf.Bytes())
	default:
		// Decode the JSON to a map[string]interface{} and then unmarshal it again to the correct format.
		var m map[string]any
		if err := json.Unmarshal(buf.Bytes(), &m); err != nil {
			return err
		}
		hmaps.ConvertFloat64WithNoDecimalsToInt(m)
		switch format {
		case "yaml":
			return parser.InterfaceToConfig(m, metadecoders.YAML, os.Stdout)
		case "toml":
			return parser.InterfaceToConfig(m, metadecoders.TOML, os.Stdout)
		default:
			return fmt.Errorf("unsupported format: %q", format)
		}
	}

	return nil
}

func (c *configCommand) Init(cd *simplecobra.Commandeer) error {
	c.r = cd.Root.Command.(*rootCommand)
	cmd := cd.CobraCommand
	cmd.Short = "Display project configuration"
	cmd.Long = `Display project configuration, both default and custom settings.`
	cmd.Flags().StringVar(&c.format, "format", "toml", "preferred file format (toml, yaml or json)")
	_ = cmd.RegisterFlagCompletionFunc("format", cobra.FixedCompletions([]string{"toml", "yaml", "json"}, cobra.ShellCompDirectiveNoFileComp))
	cmd.Flags().StringVar(&c.lang, "lang", "", "the language to display config for. Defaults to the first language defined.")
	cmd.Flags().BoolVar(&c.printZero, "printZero", false, `include config options with zero values (e.g. false, 0, "") in the output`)
	_ = cmd.RegisterFlagCompletionFunc("lang", cobra.NoFileCompletions)
	applyLocalFlagsBuildConfig(cmd, c.r)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Use one of the three supported values exactly: `--format toml`, `--format yaml`, or `--format json` (case-insensitive).
2. Change `yml` to `yaml` — the short spelling is not accepted.
3. If the flag comes from a script variable, print/validate it before invoking hugo.

Example fix

# before
hugo config --format yml
# after
hugo config --format yaml

var supported = map[string]bool{"json": true, "toml": true, "yaml": true}
if !supported[strings.ToLower(format)] {
    return fmt.Errorf("format must be one of: json, toml, yaml")
}

if err != nil && strings.HasPrefix(err.Error(), "unsupported format") {
    // print the allowed format list and exit
}

When it happens

Trigger: Running `hugo config --format <x>` with any value other than toml, yaml, or json — e.g. `--format yml`, `--format xml`, `--format JSON5`, or an empty/typoed value passed via a script or alias.

Common situations: Using `yml` instead of `yaml` (a very common habit from other tools); CI scripts templating the flag from a variable that resolves to an unexpected value; expecting formats Hugo can read (JSON5, org, etc.) to also be supported as config-dump output.

Related errors

• language %q not found
• Unable to locate config file or config directory. Perhaps yo
• ErrNoConfigFile
• failed to parse clock: %s
• no existing content directory configured for this project

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/6d381f053ee15560.json. Report an issue: GitHub ↗.