grpc-ecosystem/grpc-gateway · error

the provided format %q is not a valid extension of the type

Error message

the provided format %q is not a valid extension of the type %q

What it means

Validation error from validateDefaultValueTypeAndFormat: for a string-typed header parameter, the supplied format extension is not one of the permitted string formats (byte, date, date-time, password, binary, and the listed numeric-name strings, or empty). The offending inputs are the header type/format pair from the openapiv2 options.

Source

Thrown at protoc-gen-openapiv2/internal/genopenapi/template.go:2729

			"uint64",
			"int",
			"int8",
			"int16",
			"int32",
			"int64",
			"float",
			"float32",
			"float64",
			"complex64",
			"complex128",
			"double",
			"byte",
			"rune",
			"uintptr",
			"":
			return nil
		default:
			return fmt.Errorf("the provided format %q is not a valid extension of the type %q", format, headerType)
		}
	case "integer":
		switch format {
		case "uint",
			"uint8",
			"uint16",
			"uint32",
			"uint64",
			"int",
			"int8",
			"int16",
			"int32",
			"int64",
			"":
			return nil
		default:
			return fmt.Errorf("the provided format %q is not a valid extension of the type %q", format, headerType)
		}

View on GitHub (pinned to a58a4436a3)

Solutions

1. Use a valid string format (e.g. date-time, byte) or omit the format.
2. Correct typos in the openapiv2 header option's format field.

When it happens

Trigger: Thrown at protoc-gen-openapiv2/internal/genopenapi/template.go:2729 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/149368c82fd5146b. Report an issue: GitHub.