{"record":{"id":"73fb1733046364aa","repo":"mikefarah/yq","slug":"cannot-encode-v-to-xml-only-maps-can-be-encoded","errorCode":null,"errorMessage":"cannot encode %v to XML - only maps can be encoded","messagePattern":"cannot encode (.+?) to XML - only maps can be encoded","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/encoder_xml.go","lineNumber":95,"sourceCode":"\t\t\treturn err\n\t\t}\n\t}\n\n\tswitch node.Kind {\n\tcase MappingNode:\n\t\terr := e.encodeTopLevelMap(encoder, node)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\tcase ScalarNode:\n\t\tvar charData xml.CharData = []byte(node.Value)\n\t\terr := encoder.EncodeToken(charData)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\treturn encoder.Flush()\n\tdefault:\n\t\treturn fmt.Errorf(\"cannot encode %v to XML - only maps can be encoded\", node.Tag)\n\t}\n\n\treturn encoder.EncodeToken(newLine)\n\n}\n\nfunc (e *xmlEncoder) encodeTopLevelMap(encoder *xml.Encoder, node *CandidateNode) error {\n\terr := e.encodeComment(encoder, headAndLineComment(node))\n\tif err != nil {\n\t\treturn err\n\t}\n\tfor i := 0; i < len(node.Content); i += 2 {\n\t\tkey := node.Content[i]\n\t\tvalue := node.Content[i+1]\n\n\t\tstart := xml.StartElement{Name: xml.Name{Local: key.Value}}\n\t\tlog.Debugf(\"comments of key %v\", key.Value)\n\t\terr := e.encodeComment(encoder, headAndLineComment(key))","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/encoder_xml.go#L77-L113","documentation":"The XML encoder's top-level Encode only supports mapping nodes (and bare scalars as character data); anything else — a top-level sequence, alias, or other kind — is rejected with this message. XML documents need a root element, which only a map can provide.","triggerScenarios":"Running `yq -o xml '.' file.yaml` where the root document is an array (e.g. `- a\\n- b`) or an alias node instead of a map.","commonSituations":"Converting YAML/JSON arrays (lists of records) directly to XML; output of a select/all() expression that returns a sequence; XML round-trips where the document root was an array of repeated elements.","solutions":["Wrap the array in a map, e.g. `yq -o xml '{items: .}'` so there is a root element.","Select a specific map from the sequence: `yq -o xml '.[0]'`.","Use an expression that returns a single object rather than all(...)/[...] results.","If lists are expected, restructure the source data so the root is an object with an array field."],"exampleFix":"// before\nyq -o xml '.' list.yaml        # root is an array\n// after\nyq -o xml '{items: .}' list.yaml","handlingStrategy":"validation","validationCode":"yq 'kind' file.yaml  # must be \"map\" (or \"scalar\") for -o xml","typeGuard":"// shell\n[ \"$(yq 'kind' doc.yaml)\" = \"map\" ] || yq -o xml '{root: .}' doc.yaml","tryCatchPattern":"// Go\nif err := xmlEnc.Encode(w, node); err != nil {\n    if strings.Contains(err.Error(), \"only maps can be encoded\") {\n        // wrap sequence in a map: {items: node} and retry\n    }\n}","preventionTips":["Ensure a single root object exists before XML output","Wrap sequences explicitly: `{items: .}`","Avoid all()/select expressions that return bare sequences as the final result"],"tags":["xml","encoder","unsupported-root-kind","type-mismatch"],"backgroundTag":"xml-root-must-be-map","analyzedSha":"8b5af0694bb82b41d4ae180fac9972029066f90a","analyzedAt":"2026-09-05T10:57:22.766Z","contentChangedAt":"2026-09-05T10:57:22.766Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}