{"record":{"id":"13b16d134d9f0291","repo":"grpc-ecosystem/grpc-gateway","slug":"s-components-w","errorCode":null,"errorMessage":"%s: components: %w","messagePattern":"(.+?): components: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"openapiv3-merge/internal/merge/merge.go","lineNumber":227,"sourceCode":"\t\t\td.Info = raw\n\t\tcase \"servers\":\n\t\t\td.Servers = raw\n\t\tcase \"paths\":\n\t\t\tobj, err := decodeOrderedObject(raw)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"%s: paths: %w\", in.Name, err)\n\t\t\t}\n\t\t\td.Paths = obj\n\t\tcase \"webhooks\":\n\t\t\tobj, err := decodeOrderedObject(raw)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"%s: webhooks: %w\", in.Name, err)\n\t\t\t}\n\t\t\td.Webhooks = obj\n\t\tcase \"components\":\n\t\t\tif !isJSONNull(raw) {\n\t\t\t\tif err := json.Unmarshal(raw, d.Components); err != nil {\n\t\t\t\t\treturn nil, fmt.Errorf(\"%s: components: %w\", in.Name, err)\n\t\t\t\t}\n\t\t\t}\n\t\tcase \"security\":\n\t\t\tif err := json.Unmarshal(raw, &d.Security); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"%s: security: %w\", in.Name, err)\n\t\t\t}\n\t\tcase \"tags\":\n\t\t\tif err := json.Unmarshal(raw, &d.Tags); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"%s: tags: %w\", in.Name, err)\n\t\t\t}\n\t\tcase \"externalDocs\":\n\t\t\td.ExternalDocs = raw\n\t\tdefault:\n\t\t\td.extras.set(key, raw)\n\t\t}\n\t}\n\tif _, err := dec.Token(); err != nil {\n\t\treturn nil, fmt.Errorf(\"%s: %w\", in.Name, err)","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/grpc-ecosystem/grpc-gateway/blob/a58a4436a376a4bcc7d8f10c4d4f919a8438bba9/openapiv3-merge/internal/merge/merge.go#L209-L245","documentation":"This error is returned when the top-level `components` field of an input document cannot be json.Unmarshal-ed into the library's components struct (schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks, pathItems). Note that an explicit JSON null is tolerated and skipped; any other value with an incompatible shape for one of those keys — e.g. an array where an object is expected, or a string — fails and is wrapped as `<name>: components: <cause>`.","triggerScenarios":"Calling Merge with an Input whose Data contains `\"components\": \"none\"`, `\"components\": []`, `\"components\": {\"schemas\": []}`, `\"components\": {\"securitySchemes\": \"basic\"}` — i.e. components itself or any of its known sub-keys has the wrong JSON type.","commonSituations":"Generated specs where a components sub-section was an uninitialized slice (marshals to []); hand-written specs putting a scalar where an object belongs; tool output that nests components differently; partial migrations from OpenAPI 2.0 `definitions` placed with the wrong shape.","solutions":["Fix the offending value so `components` is an object whose sub-keys are objects, e.g. \"components\": {\"schemas\": {\"Pet\": {...}}}.","Check the exact cause in the wrapped error — it names the field (e.g. `json: cannot unmarshal array into Go struct field ...`) pointing at the bad sub-key.","If components should be absent, omit the key or use null (both are handled); do not use an array or string.","Pre-validate by unmarshalling the `components` value into a map[string]map[string]json.RawMessage before calling Merge."],"exampleFix":"// before\n{\"openapi\": \"3.1.0\", \"components\": {\"schemas\": []}}\n// after\n{\"openapi\": \"3.1.0\", \"components\": {\"schemas\": {\"Pet\": {\"type\": \"object\"}}}}","handlingStrategy":"validation","validationCode":"func validateComponentsField(data []byte) error {\n\tvar doc struct {\n\t\tComponents json.RawMessage `json:\"components\"`\n\t}\n\tif err := json.Unmarshal(data, &doc); err != nil {\n\t\treturn err\n\t}\n\tif len(doc.Components) == 0 || string(doc.Components) == \"null\" {\n\t\treturn nil\n\t}\n\tvar c map[string]map[string]json.RawMessage\n\tif err := json.Unmarshal(doc.Components, &c); err != nil {\n\t\treturn fmt.Errorf(\"components must be an object of objects: %w\", err)\n\t}\n\treturn nil\n}","typeGuard":"func isComponentsObject(raw json.RawMessage) bool {\n\tvar c map[string]map[string]json.RawMessage\n\treturn len(raw) > 0 && string(raw) != \"null\" && json.Unmarshal(raw, &c) == nil\n}","tryCatchPattern":"merged, err := merger.Merge(inputs)\nif err != nil {\n\tif strings.Contains(err.Error(), \": components: \") {\n\t\treturn fmt.Errorf(\"input spec has a malformed components field: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Keep every components sub-key (schemas, responses, securitySchemes, ...) an object, never an array or scalar.","Ensure generated structs use map types (not slices) for all components sub-sections.","Omit components or set it to null when empty — both are accepted; avoid other placeholders.","Validate specs against the OpenAPI 3.x JSON Schema before merging."],"tags":["json","openapi","type-mismatch","parsing"],"backgroundTag":"json-unmarshal-type-error","analyzedSha":"a58a4436a376a4bcc7d8f10c4d4f919a8438bba9","analyzedAt":"2026-09-02T10:28:31.537Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T16:17:10.729Z"}