{"record":{"id":"5ba3f2a9f35319a4","repo":"googleapis/mcp-toolbox","slug":"document-d-s","errorCode":null,"errorMessage":"document %d: %s","messagePattern":"document (.+?): (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/server/config.go","lineNumber":197,"sourceCode":"\t// take precedence regardless of document order.\n\tvar toolsetGroups map[string]group.GroupConfig\n\t// promptset configs is not yet supported\n\n\tfile, err := parser.ParseBytes(raw, 0)\n\tif err != nil {\n\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"unable to parse YAML: %s\", yaml.FormatError(err, false, false))\n\t}\n\n\tdecoder := yaml.NewDecoder(bytes.NewReader(raw))\n\tfor index, doc := range file.Docs {\n\t\tif doc == nil || doc.Body == nil {\n\t\t\tcontinue\n\t\t}\n\t\tdocIndex := index + 1\n\t\tvar resource map[string]any\n\t\tif err := decoder.DecodeFromNodeContext(ctx, doc.Body, &resource); err != nil {\n\t\t\tif len(file.Docs) > 1 {\n\t\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"document %d: %s\", docIndex, yaml.FormatError(err, false, false))\n\t\t\t}\n\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"unable to decode YAML document: %s\", yaml.FormatError(err, false, false))\n\t\t}\n\t\tvar kind, name string\n\t\tvar ok bool\n\t\tif kind, ok = resource[\"kind\"].(string); !ok {\n\t\t\tif len(file.Docs) > 1 {\n\t\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"%s missing 'kind' field or it is not a string\", formatDocLocation(docIndex, keyToken(doc.Body, \"kind\"), doc.Body))\n\t\t\t}\n\t\t\treturn nil, nil, nil, nil, nil, nil, fmt.Errorf(\"missing 'kind' field or it is not a string: %v\", resource)\n\t\t}\n\t\tif name, ok = resource[\"name\"].(string); !ok {\n\t\t\t// A `kind: group` may omit `name` to target the default nameless group;\n\t\t\t// every other resource requires a name.\n\t\t\tif kind == \"group\" {\n\t\t\t\tif rawName, present := resource[\"name\"]; !present || rawName == nil {\n\t\t\t\t\tname, ok = \"\", true\n\t\t\t\t}","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/server/config.go#L179-L215","documentation":"When the tools file contains multiple YAML documents (--- separated), a per-document decode failure is reported as `document %d: <yaml error>` with the 1-based document index. It wraps yaml.FormatError output so the offending line inside that document can be located. A single-document file uses the more generic message instead (error 159).","triggerScenarios":"A multi-document tools.yaml where one document's body cannot be decoded into map[string]any — e.g. a document that is a list/scalar instead of a mapping, or node-level type mismatches during DecodeFromNodeContext.","commonSituations":"Appending a second config document with `---` that has a structural error, generating configs programmatically producing non-mapping documents, merging config files incorrectly.","solutions":["Locate the Nth document (count `---` separators) and fix the reported YAML error inside it","Ensure every document is a YAML mapping with kind/name keys","Temporarily split documents into separate files to isolate the broken one","Validate each document independently with a YAML parser"],"exampleFix":"// before\ndocs:\n---\n- kind: tool   # document is a list, not a mapping\n// after\ndocs:\n---\nkind: tool\nname: my-tool","handlingStrategy":"validation","validationCode":"const docs = fs.readFileSync('tools.yaml','utf8').split(/^---$/m);\ndocs.forEach((d, i) => {\n  const parsed = require('yaml').parse(d);\n  if (typeof parsed !== 'object' || Array.isArray(parsed) || parsed === null)\n    throw new Error(`document ${i+1} must be a mapping`);\n  if (!('kind' in parsed)) throw new Error(`document ${i+1} missing 'kind'`);\n});","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate each `---`-separated document is a mapping with kind/name","Split multi-doc files when debugging to isolate failures","Lint multi-document YAML with yq or a parser in CI"],"tags":["yaml","config","multi-document","startup"],"backgroundTag":"yaml-parse-error","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"}