grpc-ecosystem/grpc-gateway · error

unknown format:

Error message

unknown format: 

What it means

Validation error from Format.Validate: the supplied output Format string is neither "json" nor "yaml". protoc-gen-openapiv2 only supports these two output encodings, so any other value (e.g. from the openapiv2_out format option) is rejected before encoding.

Source

Thrown at protoc-gen-openapiv2/internal/genopenapi/format.go:27

)

type Format string

const (
	FormatJSON Format = "json"
	FormatYAML Format = "yaml"
)

type ContentEncoder interface {
	Encode(v interface{}) (err error)
}

func (f Format) Validate() error {
	switch f {
	case FormatJSON, FormatYAML:
		return nil
	default:
		return errors.New("unknown format: " + string(f))
	}
}

func (f Format) NewEncoder(w io.Writer) (ContentEncoder, error) {
	switch f {
	case FormatYAML:
		enc := yaml.NewEncoder(w)
		enc.SetIndent(2)

		return enc, nil
	case FormatJSON:
		enc := json.NewEncoder(w)
		enc.SetIndent("", "  ")

		return enc, nil
	default:
		return nil, errors.New("unknown format: " + string(f))
	}

View on GitHub (pinned to a58a4436a3)

Solutions

1. Set the output format option to "json" or "yaml".
2. Check for typos or stray whitespace/casing in the format parameter.

When it happens

Trigger: Thrown at protoc-gen-openapiv2/internal/genopenapi/format.go:27 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of grpc-ecosystem/grpc-gateway@a58a4436a3 (2026-09-02). Data as JSON: /api/errors/05227cae09aaaad0. Report an issue: GitHub.