mikefarah/yq · error

unknown format ' ' please use [ ]

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.

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.

Appendix: 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)