grpc-ecosystem/grpc-gateway · error

failed to resolve method FQN: '%s'

Error message

failed to resolve method FQN: '%s'

What it means

Registry lookup error surfaced in renderServices: the generator failed to resolve a binding method's request-type fully-qualified name (meth.RequestType FQMN) when building the request schema/ref. The error names the FQMN string; the input at fault is a method whose request message cannot be located in the registry.

Source

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

							// Special workaround for Empty: it's well-known type but wknSchemas only returns schema.schemaCore; but we need to set schema.Properties which is a level higher.
							if meth.RequestType.FQMN() == ".google.protobuf.Empty" {
								schema.Properties = &openapiSchemaObjectProperties{}
							}
						} else {
							messageSchema, err := renderMessageAsDefinition(meth.RequestType, reg, customRefs, b.PathParams)
							if err != nil {
								return err
							}
							if len(b.PathParams) == 0 {
								if err := schema.setRefFromFQN(meth.RequestType.FQMN(), reg); err != nil {
									return err
								}
								desc = messageSchema.Description
							} else {
								if meth.Name != nil {
									methFQN, ok := fullyQualifiedNameToOpenAPIName(meth.FQMN(), reg)
									if !ok {
										panic(fmt.Errorf("failed to resolve method FQN: '%s'", meth.FQMN()))
									}
									defName := methFQN + "Body"
									schema.Ref = fmt.Sprintf("#/definitions/%s", defName)
									defs[defName] = messageSchema
								} else {
									schema = messageSchema
									if schema.Properties == nil || len(*schema.Properties) == 0 {
										grpclog.Warningf("created a body with 0 properties in the message, this might be unintended: %s", *meth.RequestType)
									}
								}
							}
						}
					} else {
						// google.api.HttpRule.body documents body fields as top-level request fields:
						// "NOTE: the referred field must be present at the top-level of the request message type."
						// Ref: https://github.com/googleapis/googleapis/blob/b3397f5febbf21dfc69b875ddabaf76bee765058/google/api/http.proto#L350-L352
						// grpc-gateway accepts nested body field paths when generating gateway handlers,
						// so OpenAPI rendering also follows the full path and uses the terminal field type.

View on GitHub (pinned to a58a4436a3)

Solutions

1. Ensure the request message type is defined/imported in the analyzed proto set.
2. Check that the method's input_type is set correctly and descriptors are complete.
3. Regenerate with the same descriptor set passed to the plugin.

When it happens

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