{"record":{"id":"31e7bb1352fc739f","repo":"grpc-ecosystem/grpc-gateway","slug":"s-paths-w","errorCode":null,"errorMessage":"%s: paths: %w","messagePattern":"(.+?): paths: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"openapiv3-merge/internal/merge/merge.go","lineNumber":215,"sourceCode":"\t\t\treturn nil, fmt.Errorf(\"%s: unexpected token %v\", in.Name, tok)\n\t\t}\n\t\tvar raw json.RawMessage\n\t\tif err := dec.Decode(&raw); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"%s: %q: %w\", in.Name, key, err)\n\t\t}\n\t\tswitch key {\n\t\tcase \"openapi\":\n\t\t\tif err := json.Unmarshal(raw, &d.OpenAPI); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"%s: openapi: %w\", in.Name, err)\n\t\t\t}\n\t\tcase \"info\":\n\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}","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/grpc-ecosystem/grpc-gateway/blob/a58a4436a376a4bcc7d8f10c4d4f919a8438bba9/openapiv3-merge/internal/merge/merge.go#L197-L233","documentation":"This error is returned when the top-level `paths` field of an input document is not a JSON object. parse calls decodeOrderedObject on the raw value to preserve path insertion order; decodeOrderedObject requires the value to be a JSON object mapping path strings to path items, so arrays, strings, numbers, booleans, or null produce a decode error wrapped as `<name>: paths: <cause>`.","triggerScenarios":"Calling Merge with an Input whose Data has `\"paths\": []` (array), `\"paths\": \"...\"`, `\"paths\": null`, or any non-object value under the `paths` key.","commonSituations":"Specs serialized from structs where Paths was an uninitialized nil slice (marshals to null or []); template scaffolds with a placeholder array; tools emitting `paths` as a list of path descriptors instead of a map; hand-edits that replaced the object with an empty array.","solutions":["Edit the input so `paths` is a JSON object, e.g. \"paths\": {\"/pets\": {...}} (use {} for no paths).","If generating JSON from Go/other structs, initialize Paths as a map so it marshals as {} instead of null or [].","Fix whatever produced the spec so it emits a map of path-keyed entries rather than a list.","Pre-validate: decode the `paths` value into map[string]json.RawMessage before calling Merge to catch it early."],"exampleFix":"// before\n{\"openapi\": \"3.1.0\", \"paths\": []}\n// after\n{\"openapi\": \"3.1.0\", \"paths\": {\"/health\": {\"get\": {\"responses\": {\"200\": {\"description\": \"ok\"}}}}}","handlingStrategy":"validation","validationCode":"func validatePathsField(data []byte) error {\n\tvar doc struct {\n\t\tPaths json.RawMessage `json:\"paths\"`\n\t}\n\tif err := json.Unmarshal(data, &doc); err != nil {\n\t\treturn err\n\t}\n\tif len(doc.Paths) == 0 || string(doc.Paths) == \"null\" {\n\t\treturn nil\n\t}\n\tvar m map[string]json.RawMessage\n\tif err := json.Unmarshal(doc.Paths, &m); err != nil {\n\t\treturn fmt.Errorf(\"paths must be a JSON object: %w\", err)\n\t}\n\treturn nil\n}","typeGuard":"func isJSONObject(raw json.RawMessage) bool {\n\tvar m map[string]json.RawMessage\n\treturn len(raw) > 0 && json.Unmarshal(raw, &m) == nil\n}","tryCatchPattern":"merged, err := merger.Merge(inputs)\nif err != nil {\n\tif strings.Contains(err.Error(), \": paths: \") {\n\t\treturn fmt.Errorf(\"input spec has a non-object paths field: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Initialize paths as {} (or an empty map) when generating specs, never null or [].","Validate specs against the OpenAPI 3.x JSON Schema before merging.","Keep paths as a keyed map end-to-end; never convert to arrays during transformation.","Lint specs in CI for top-level field types before running the merge step."],"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"}