grpc-ecosystem/grpc-gateway · error

unknown enum type

Error message

unknown enum type %s

What it means

In genopenapi's nestedQueryParams, when a query parameter field is an enum, the registry is asked to look up the enum type; failure produces 'unknown enum type %s'. This means the enum referenced by a query-path field cannot be found in the registry — the descriptor wasn't loaded or the type name doesn't match any registered enum.

Solutions

1. Include the proto file that defines the enum (and its transitive deps) in the protoc invocation.
2. Verify the enum name/path in the referencing proto matches the actual definition.
3. Regenerate all descriptors together so registry entries for the enum exist.
4. As a last resort, avoid exposing that enum-typed field in query parameters (restructure the nested message path).

Example fix

// before
protoc --openapiv2_out=. service.proto  # service.proto uses enums from types.proto

// after
protoc -I . --openapiv2_out=. service.proto types.proto

// Check the enum is resolvable before doc generation:
if _, err := reg.LookupEnum("", "my.pkg.MyEnum"); err != nil {
    return fmt.Errorf("enum %s not registered; add its file to protoc args", "my.pkg.MyEnum")
}

When it happens

Trigger: queryParams/nestedQueryParams recursion hits an enum field whose reg.LookupEnum("", fieldType) fails — enum defined in a dependency not included in the protoc run, or a type-name mismatch (fieldType string not matching any registered enum FQMN).

Common situations: Query parameters reaching into messages from external packages (google.type, third-party protos) whose enum definitions weren't passed to protoc; renamed/moved enums with stale references; generating OpenAPI from a subset of files.

Related errors

• unknown message type
• can't map OpenAPI name from FQMN
• can't resolve OpenAPI name from
• exceeded recursive count
• failed to encode OpenAPI for

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

Appendix: source

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

			Items:       schema.Items,
			Format:      schema.Format,
			Pattern:     schema.Pattern,
			Required:    required,
			Deprecated:  deprecated,
			UniqueItems: schema.UniqueItems,
			extensions:  schema.extensions,
			Enum:        schema.Enum,
		}
		if param.Type == "array" {
			param.CollectionFormat = "multi"
		}

		param.Name = prefix + reg.FieldName(field)

		if isEnum {
			enum, err := reg.LookupEnum("", fieldType)
			if err != nil {
				return nil, fmt.Errorf("unknown enum type %s", fieldType)
			}
			if items != nil { // array
				param.Items = &openapiItemsObject{
					schemaCore: schemaCore{
						Type: "string",
						Enum: listEnumNames(reg, enum),
					},
				}
				if reg.GetEnumsAsInts() {
					param.Items.Type = "integer"
					param.Items.Enum = listEnumNumbers(reg, enum)
				}
			} else {
				param.Type = "string"
				param.Enum = listEnumNames(reg, enum)
				param.Default = getEnumDefault(reg, enum)
				if reg.GetEnumsAsInts() {
					param.Type = "integer"

View on GitHub (pinned to a58a4436a3)