grpc-ecosystem/grpc-gateway · error

unknown enum type %s

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.

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)

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 %s
• failed to lookup message type %s: %w
• failed to encode OpenAPI for %s: %w
• exceeded recursive count (%d) for query parameter %q
• unsupported type: %q

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