{"record":{"id":"0e4f8e15afb4b758","repo":"googleapis/mcp-toolbox","slug":"document-d-error-unmarshaling-s-q-w","errorCode":null,"errorMessage":"document %d: error unmarshaling %s %q: %w","messagePattern":"document (.+?): error unmarshaling (.+?) %q: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/server/config.go","lineNumber":236,"sourceCode":"\t\tif !ok {\n\t\t\tif len(file.Docs) > 1 {\n\t\t\t\tfallbackToken := keyToken(doc.Body, \"name\")\n\t\t\t\tif fallbackToken == nil {\n\t\t\t\t\tfallbackToken = keyToken(doc.Body, \"kind\")\n\t\t\t\t}\n\t\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"%s missing 'name' field or it is not a string\", formatDocLocation(docIndex, fallbackToken, doc.Body))\n\t\t\t}\n\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"missing 'name' field or it is not a string\")\n\t\t}\n\t\t// remove 'kind' from map for strict unmarshaling\n\t\tdelete(resource, \"kind\")\n\n\t\tswitch kind {\n\t\tcase \"source\":\n\t\t\tc, err := UnmarshalYAMLSourceConfig(ctx, name, resource)\n\t\t\tif err != nil {\n\t\t\t\tif len(file.Docs) > 1 {\n\t\t\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"document %d: error unmarshaling %s %q: %w\", docIndex, kind, name, err)\n\t\t\t\t}\n\t\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"error unmarshaling %s: %w\", kind, err)\n\t\t\t}\n\t\t\tif sourceConfigs == nil {\n\t\t\t\tsourceConfigs = make(SourceConfigs)\n\t\t\t}\n\t\t\tif _, exists := sourceConfigs[name]; exists {\n\t\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"source %q declared more than once\", name)\n\t\t\t}\n\t\t\tsourceConfigs[name] = c\n\t\tcase \"authService\":\n\t\t\tc, err := UnmarshalYAMLAuthServiceConfig(ctx, name, resource)\n\t\t\tif err != nil {\n\t\t\t\tif len(file.Docs) > 1 {\n\t\t\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"document %d: error unmarshaling %s %q: %w\", docIndex, kind, name, err)\n\t\t\t\t}\n\t\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"error unmarshaling %s: %w\", kind, err)\n\t\t\t}","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/server/config.go#L218-L254","documentation":"After kind/name validation, UnmarshalPrimitiveConfig dispatches each document to a type-specific unmarshaler (e.g. UnmarshalYAMLSourceConfig). This error wraps the underlying unmarshaler failure with the document index, kind, and name. The %w-wrapped cause carries the real problem (unknown kind variant, bad field types, strict-mode unknown fields).","triggerScenarios":"ParseConfig on a multi-document YAML file where document N's resource map fails strict YAML decoding into the config struct for its kind (e.g. a source with an invalid 'kind' subtype like kind: postgres with unknown/mistyped fields).","commonSituations":"Typos in source/tool parameter names; wrong types (host as integer); unsupported source kind inside the doc; schema drift after a toolbox version upgrade removed or renamed a field.","solutions":["Read the wrapped cause (%w) at the end of the error for the exact field/decoding problem.","Fix the field name or value type in document N indicated in the message.","Check the docs for the specific source/tool to confirm supported fields and types.","If a field was removed in a toolbox upgrade, migrate the config to the new schema."],"exampleFix":"// before\nkind: postgres\nname: db\nprot: 5432\n// after\nkind: postgres\nname: db\nport: 5432","handlingStrategy":"validation","validationCode":"// Parse a draft config and surface the wrapped cause before deploying\ncfg, _, _, _, _, _, err := server.ParseConfig(ctx, params)\nif err != nil {\n    var inner error\n    for e := err; e != nil; e = errors.Unwrap(e) { inner = e }\n    return fmt.Errorf(\"config invalid (see cause): %w\", inner)\n}","typeGuard":null,"tryCatchPattern":"if _, err := server.ParseConfig(ctx, params); err != nil {\n    var docErr = err\n    for errors.Unwrap(docErr) != nil { docErr = errors.Unwrap(docErr) }\n    log.Fatalf(\"YAML unmarshal failed at the indicated document: root=%v cause=%v\", err, docErr)\n}","preventionTips":["Diff YAML fields against the current version's source/tool docs on every toolbox upgrade.","Use strict YAML linting with a schema per kind.","Avoid guessing field names; copy from documented examples.","Add a CI step that parses every config file before merge."],"tags":["yaml","config","unmarshaling"],"backgroundTag":"yaml-unmarshal-failed","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}