{"record":{"id":"6352a91a9fe0db5c","repo":"mikefarah/yq","slug":"csv-encoding-only-works-for-arrays-got-v","errorCode":null,"errorMessage":"csv encoding only works for arrays, got: %v","messagePattern":"csv encoding only works for arrays, got: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/encoder_csv.go","lineNumber":115,"sourceCode":"\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t}\n\treturn nil\n}\n\nfunc (e *csvEncoder) Encode(writer io.Writer, node *CandidateNode) error {\n\tif node.Kind == ScalarNode {\n\t\treturn writeString(writer, node.Value+\"\\n\")\n\t}\n\n\tcsvWriter := csv.NewWriter(writer)\n\tcsvWriter.Comma = e.separator\n\n\t// node must be a sequence\n\tif node.Kind != SequenceNode {\n\t\treturn fmt.Errorf(\"csv encoding only works for arrays, got: %v\", node.Tag)\n\t} else if len(node.Content) == 0 {\n\t\treturn nil\n\t}\n\tif node.Content[0].Kind == ScalarNode {\n\t\treturn e.encodeRow(csvWriter, node.Content)\n\t}\n\n\tif node.Content[0].Kind == MappingNode {\n\t\treturn e.encodeObjects(csvWriter, node.Content)\n\t}\n\n\treturn e.encodeArrays(csvWriter, node.Content)\n\n}\n","sourceCodeStart":97,"sourceCodeEnd":130,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/encoder_csv.go#L97-L130","documentation":"The CSV encoder requires the node being encoded to be a sequence (array) at the root — either an array of scalar rows or an array of flat objects. This error is thrown when the top-level node passed to the CSV encoder is a scalar or mapping instead of an array.","triggerScenarios":"`yq -o csv '{a: 1}'` (root is a map) or `yq -o csv '\"hello\"'` (root is a scalar); also wrapping a single object without putting it in an array.","commonSituations":"Forgetting to wrap a single object with `[...]` or `[]` in the expression; piping `-o csv` onto documents that are maps; users expecting CSV of a single record to work directly.","solutions":["Wrap the data in an array: `yq -o csv '[.]'` or `yq -o csv '[.records[]]'`","Use `map(...)` / `to_entries` to produce an array before encoding","Choose a different output format (JSON/YAML) for non-array data"],"exampleFix":"// before: yq -o csv '{a: 1, b: 2}'\n// after:  yq -o csv '[{a: 1, b: 2}]'","handlingStrategy":"validation","validationCode":"yq 'type == \"!!seq\"' input.yaml   # must print true before -o csv","typeGuard":"func isSequence(node *CandidateNode) bool { return node.Kind == SequenceNode }","tryCatchPattern":"out, err := encoder.Encode(node)\nif err != nil && strings.Contains(err.Error(), \"csv encoding only works for arrays\") {\n    // wrap in array: ctx = singleChildContext(candidate.CreateReplacement(SequenceNode, \"!!seq\", ...))\n}","preventionTips":["Always feed an array to `-o csv`; wrap single objects with `[.]`","Check the root `type` before choosing CSV output","Use JSON output when the data is not an array"],"tags":["csv","encoding","root-node","yq"],"backgroundTag":"csv-root-must-be-array","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"}