{"record":{"id":"1c6772b438ef2d91","repo":"grpc-ecosystem/grpc-gateway","slug":"can-t-map-openapi-name-from-fqmn-q","errorCode":null,"errorMessage":"can't map OpenAPI name from FQMN %q","messagePattern":"can't map OpenAPI name from FQMN %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"protoc-gen-openapiv2/internal/genopenapi/template.go","lineNumber":1236,"sourceCode":"\t\tret, ok := mapping[fqn]\n\t\treturn ret, ok\n\t}\n\tmapping := resolveFullyQualifiedNameToOpenAPINames(append(reg.GetAllFQMNs(), append(reg.GetAllFQENs(), reg.GetAllFQMethNs()...)...), reg.GetOpenAPINamingStrategy())\n\tregistriesSeen[reg] = mapping\n\tret, ok := mapping[fqn]\n\treturn ret, ok\n}\n\n// Lookup message type by location.name and return an openapiv2-safe version\n// of its FQMN.\nfunc lookupMsgAndOpenAPIName(location, name string, reg *descriptor.Registry) (*descriptor.Message, string, error) {\n\tmsg, err := reg.LookupMsg(location, name)\n\tif err != nil {\n\t\treturn nil, \"\", err\n\t}\n\tswgName, ok := fullyQualifiedNameToOpenAPIName(msg.FQMN(), reg)\n\tif !ok {\n\t\treturn nil, \"\", fmt.Errorf(\"can't map OpenAPI name from FQMN %q\", msg.FQMN())\n\t}\n\treturn msg, swgName, nil\n}\n\n// registriesSeen is used to memoise calls to resolveFullyQualifiedNameToOpenAPINames so\n// we don't repeat it unnecessarily, since it can take some time.\nvar (\n\tregistriesSeen      = map[*descriptor.Registry]map[string]string{}\n\tregistriesSeenMutex sync.Mutex\n)\n\n// Take the names of every proto message and generate a unique reference for each, according to the given strategy.\nfunc resolveFullyQualifiedNameToOpenAPINames(messages []string, namingStrategy string) map[string]string {\n\tstrategyFn := LookupNamingStrategy(namingStrategy)\n\tif strategyFn == nil {\n\t\treturn nil\n\t}\n\treturn strategyFn(messages)","sourceCodeStart":1218,"sourceCodeEnd":1254,"githubUrl":"https://github.com/grpc-ecosystem/grpc-gateway/blob/a58a4436a376a4bcc7d8f10c4d4f919a8438bba9/protoc-gen-openapiv2/internal/genopenapi/template.go#L1218-L1254","documentation":"lookupMsgAndOpenAPIName resolves a message reference for template rendering: it looks up the message in the registry and then maps its FQMN to an OpenAPI schema name. If reg.LookupMsg succeeds but fullyQualifiedNameToOpenAPIName fails, it returns 'can't map OpenAPI name from FQMN %q'. This mirrors error 108 but for a directly referenced message (e.g. a request/response type), meaning the message exists yet its OpenAPI name was never computed by the name-resolution pass.","triggerScenarios":"applyTemplate resolving a request/response or referenced message where reg.LookupMsg(location, name) succeeds but fullyQualifiedNameToOpenAPIName(msg.FQMN(), reg) returns false — the FQMN is absent from the resolved OpenAPI-name table built earlier in generation.","commonSituations":"RPC referencing messages from dependency protos whose name resolution was skipped or inconsistent (partial protoc invocation); package naming collisions affecting the uniquifier; custom naming/registry manipulations in plugins that bypass resolveFullyQualifiedNameToOpenAPINames.","solutions":["Run protoc-gen-openapiv2 over the complete set of protos (all dependencies) so every referenced FQMN is in the name map.","Ensure consistent proto package declarations; fix collisions that break FQMN→OpenAPI-name mapping.","Check the referenced message's package/name spelling in the RPC signature.","Upgrade protoc-gen-openapiv2 to the latest release to pick up name-resolution fixes."],"exampleFix":"// before: generating docs for service.proto only, response type from common.proto missing from name map\nprotoc --openapiv2_out=. service.proto\n// after\nprotoc -I . --openapiv2_out=. service.proto common.proto","handlingStrategy":"validation","validationCode":"// Before doc generation, confirm every RPC-referenced type maps to an OpenAPI name:\nfor _, svc := range services {\n    for _, m := range svc.Methods {\n        if _, ok := fullyQualifiedNameToOpenAPIName(m.RequestType.FQMN(), reg); !ok {\n            return fmt.Errorf(\"request type %s unmapped; include its file in protoc\", m.RequestType.FQMN())\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Include all dependency protos when generating OpenAPI output.","Verify package declarations are consistent across the API surface.","Run doc generation over the complete descriptor set in CI."],"tags":["codegen","openapi","name-resolution","fqmn"],"backgroundTag":"openapi-name-resolution-failed","analyzedSha":"a58a4436a376a4bcc7d8f10c4d4f919a8438bba9","analyzedAt":"2026-09-02T10:28:31.537Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T16:17:10.729Z"}