mikefarah/yq · error

unknown format '%v' please use [%v]

Error message

unknown format '%v' please use [%v]

What it means

FormatFromString was asked for a format name (or alias) that matches none of the registered Formats — the string passed via -p/-o/--from or the file-extension lookup has a typo or names a format compiled out of this build (build-tag formats can be excluded). The message helpfully lists every available output format name.

Source

Thrown at pkg/yqlib/format.go:151

				return format
			}
			GetLogger().Debugf("extension '%s' is not a recognised format, defaulting to yaml", format)
		}
	}

	GetLogger().Debugf("using default inputFormat 'yaml'")
	return "yaml"
}

func FormatFromString(format string) (*Format, error) {
	if format != "" {
		for _, printerFormat := range Formats {
			if printerFormat.MatchesName(format) {
				return printerFormat, nil
			}
		}
	}
	return nil, fmt.Errorf("unknown format '%v' please use [%v]", format, GetAvailableOutputFormatString())
}

func GetAvailableOutputFormats() []*Format {
	var formats = []*Format{}
	for _, printerFormat := range Formats {
		if printerFormat.EncoderFactory != nil {
			formats = append(formats, printerFormat)
		}
	}
	return formats
}

func GetAvailableOutputFormatString() string {
	var formats = []string{}
	for _, printerFormat := range GetAvailableOutputFormats() {

		if printerFormat.FormalName != "" {
			formats = append(formats, printerFormat.FormalName)

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Use one of the formats listed in the error message
2. Check for typos in the format flag (e.g. 'jsn' vs 'json'; valid short aliases include @json/@yq style names)
3. If the format should exist, rebuild yq without the yq_no<format> build tag
4. Omit the flag to fall back to the default yaml format

When it happens

Trigger: Thrown at pkg/yqlib/format.go:151 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of mikefarah/yq@8b5af0694b (2026-09-05). Data as JSON: /api/errors/637473a9716e4a1c. Report an issue: GitHub.