{"record":{"id":"ea8150e341a879f0","repo":"googleapis/mcp-toolbox","slug":"unable-to-decode-yaml-document-s","errorCode":null,"errorMessage":"unable to decode YAML document: %s","messagePattern":"unable to decode YAML document: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/server/config.go","lineNumber":199,"sourceCode":"\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}\n\t\t\t}\n\t\t}","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/server/config.go#L181-L217","documentation":"When the tools file has a single YAML document and yaml.Decoder.DecodeFromNodeContext fails to decode it into a resource map, the config loader aborts with `unable to decode YAML document: <formatted error>`. Unlike the multi-document case, no document index is shown since there is only one.","triggerScenarios":"Loading a single-document tools.yaml whose root is not decodable into map[string]any (e.g. the file starts with a list or scalar), or YAML content that parses but fails node decoding due to duplicate keys/type conflicts.","commonSituations":"Replacing tools.yaml contents with a plain list of tools, truncating the file so only a fragment remains, accidentally saving logs or JSON into the tools file.","solutions":["Ensure the top level of the file is a mapping (sources:, tools:, etc.), not a list or scalar","Restore the full file structure (kind/name on resources) from the docs examples","Check the embedded yaml.FormatError message for the failing line/column","Validate the file parses to an object: `yq eval '.' tools.yaml`"],"exampleFix":"// before\n- kind: source\n  name: my-pg\n// after\nsources:\n  my-pg:\n    kind: postgres","handlingStrategy":"validation","validationCode":"const parsed = require('yaml').parse(fs.readFileSync('tools.yaml','utf8'));\nif (typeof parsed !== 'object' || Array.isArray(parsed) || parsed === null) {\n  throw new Error('tools.yaml root must be a mapping (sources:, tools:, ...)');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the top-level structure as a mapping with sources/tools keys","Restore from documented examples after edits","Validate with `yq eval '.' tools.yaml` before starting the server"],"tags":["yaml","config","decode","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"}