grpc-ecosystem/grpc-gateway · error

extension keys need to start with "x-": %q

Error message

extension keys need to start with "x-": %q

What it means

Spec-validation error from processExtensions: an extension key in the openapiv2 options does not begin with the OpenAPI-mandated 'x-' prefix, which would produce a non-conformant vendor extension. The offending input is the extension map key reported in the message.

Source

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

						}
					}
				}
				matched = true
				break
			}
		}
		if !matched {
			existingTags = append(existingTags, tag)
		}
	}
	return existingTags
}

func processExtensions(inputExts map[string]*structpb.Value) ([]extension, error) {
	exts := make([]extension, 0, len(inputExts))
	for k, v := range inputExts {
		if !strings.HasPrefix(k, "x-") {
			return nil, fmt.Errorf("extension keys need to start with \"x-\": %q", k)
		}
		ext, err := (&protojson.MarshalOptions{Indent: "  "}).Marshal(v)
		if err != nil {
			return nil, err
		}
		exts = append(exts, extension{key: k, value: ext})
	}
	sort.Slice(exts, func(i, j int) bool { return exts[i].key < exts[j].key })
	return exts, nil
}

func validateHeaderTypeAndFormat(headerType, format string) error {
	// The type of the object. The value MUST be one of "string", "number", "integer", "boolean", or "array"
	// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#headerObject
	// Note: currently not implementing array as we are only implementing this in the operation response context
	switch headerType {
	// the format property is an open string-valued property, and can have any value to support documentation needs
	// primary check for format is to ensure that the number/integer formats are extensions of the specified type

View on GitHub (pinned to a58a4436a3)

Solutions

1. Rename the extension key to start with "x-" (e.g. x-amazon-apigateway-integration).
2. Move non-extension data out of the extensions map.

When it happens

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