{"record":{"id":"5a5343cb154d070b","repo":"abiosoft/colima","slug":"unexpected-error-during-yaml-decode-doc-has-multi","errorCode":null,"errorMessage":"unexpected error during yaml decode: doc has multiple children of len %d","messagePattern":"unexpected error during yaml decode: doc has multiple children of len (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"util/yamlutil/yaml.go","lineNumber":52,"sourceCode":"\t}\n\n\treturn nil\n}\n\nfunc encodeYAML(conf config.Config) ([]byte, error) {\n\tvar doc yaml.Node\n\n\tf, err := embedded.Read(\"defaults/colima.yaml\")\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error reading config file: %w\", err)\n\t}\n\n\tif err := yaml.Unmarshal(f, &doc); err != nil {\n\t\treturn nil, fmt.Errorf(\"embedded default config is invalid yaml: %w\", err)\n\t}\n\n\tif l := len(doc.Content); l != 1 {\n\t\treturn nil, fmt.Errorf(\"unexpected error during yaml decode: doc has multiple children of len %d\", l)\n\t}\n\troot := doc.Content[0]\n\n\t// get all nodes\n\tnodeVals := map[string]*yaml.Node{}\n\tif err := traverseNode(\"\", root, nodeVals); err != nil {\n\t\treturn nil, fmt.Errorf(\"error traversing yaml node: %w\", err)\n\t}\n\n\t// get all node values\n\tstructVals := map[string]any{}\n\ttraverseConfig(\"\", conf, structVals)\n\n\t// apply values to nodes\n\tfor key, node := range nodeVals {\n\t\tval := structVals[key]\n\n\t\t// top level, ignore. except known maps.","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/util/yamlutil/yaml.go#L34-L70","documentation":"encodeYAML (util/yamlutil/yaml.go:52) requires the unmarshaled document node to have exactly one child — the root mapping. A yaml.Node document with multiple Content children means the source YAML contained multiple documents separated by '---'. yaml.v3's Unmarshal into a single Node tolerates multi-document input, so colima defends here by rejecting it before traversal; the embedded default is a single document, so this fires only when that invariant is broken.","triggerScenarios":"An embedded/defaults/colima.yaml that gained a '---' document separator (e.g. concatenated files), producing doc.Content of length 2+.","commonSituations":"Fork merges that concatenate snippets onto the defaults file; tooling that appends generated YAML with a leading ---; copy-paste of multi-document Kubernetes-style YAML into the defaults template.","solutions":["Remove '---' separators from embedded/defaults/colima.yaml so it is exactly one document","If multiple documents are truly needed, split the file and read only the first document explicitly","Add a lint step rejecting multi-document content in the embedded defaults","Revert to the stock embedded file and layer changes through colima's config instead"],"exampleFix":"# embedded/defaults/colima.yaml (before) — two documents\nvm:\n  cpu: 4\n---\nmounts: []\n\n# after — single document\nvm:\n  cpu: 4\nmounts: []","handlingStrategy":"fallback","validationCode":"// reject multi-document YAML before it reaches encodeYAML\nfunc isSingleDocument(b []byte) bool {\n    d := yaml.NewDecoder(bytes.NewReader(b))\n    var v any\n    if err := d.Decode(&v); err != nil { return false }\n    return d.Decode(&v) == io.EOF\n}","typeGuard":null,"tryCatchPattern":"if err := util.Save(cfg, file); err != nil {\n    if strings.Contains(err.Error(), \"multiple children\") {\n        // embedded template gained '---' separators: reinstall or fix the asset\n        return fmt.Errorf(\"colima defaults corrupted (multi-doc) — reinstall: %w\", err)\n    }\n    return err\n}","preventionTips":["Keep embedded YAML single-document; no '---' separators","Use a YAML linter that flags multi-doc in assets meant to be single-doc","In forks, add the single-document test to CI"],"tags":["yaml","multi-document","embedded","internal"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}