{"record":{"id":"8cd09b0ce713a67f","repo":"mikefarah/yq","slug":"toml-encoder-expects-a-mapping-at-the-root-level","errorCode":null,"errorMessage":"TOML encoder expects a mapping at the root level","messagePattern":"TOML encoder expects a mapping at the root level","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/encoder_toml.go","lineNumber":33,"sourceCode":"\twroteRootAttr bool // Track if we wrote root-level attributes before tables\n\tprefs         TomlPreferences\n}\n\nfunc NewTomlEncoder() Encoder {\n\treturn NewTomlEncoderWithPrefs(ConfiguredTomlPreferences)\n}\n\nfunc NewTomlEncoderWithPrefs(prefs TomlPreferences) Encoder {\n\treturn &tomlEncoder{prefs: prefs}\n}\n\nfunc (te *tomlEncoder) Encode(writer io.Writer, node *CandidateNode) error {\n\tif node.Kind != MappingNode {\n\t\t// For standalone selections, TOML tests expect raw value for scalars\n\t\tif node.Kind == ScalarNode {\n\t\t\treturn writeString(writer, node.Value+\"\\n\")\n\t\t}\n\t\treturn fmt.Errorf(\"TOML encoder expects a mapping at the root level\")\n\t}\n\n\t// Encode to a buffer first if colors are enabled\n\tvar buf bytes.Buffer\n\tvar targetWriter io.Writer\n\ttargetWriter = writer\n\tif te.prefs.ColorsEnabled {\n\t\ttargetWriter = &buf\n\t}\n\n\t// Encode a root mapping as a sequence of attributes, tables, and arrays of tables\n\tif err := te.encodeRootMapping(targetWriter, node); err != nil {\n\t\treturn err\n\t}\n\n\tif te.prefs.ColorsEnabled {\n\t\tcolourised := te.colorizeToml(buf.Bytes())\n\t\t_, err := writer.Write(colourised)","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/encoder_toml.go#L15-L51","documentation":"TOML documents are tables at the root, so the TOML encoder requires a top-level MappingNode. Scalars are special-cased to print the raw value (for standalone selections), but any other Kind (sequence, alias, etc.) fails with this error.","triggerScenarios":"`yq -o toml '.someArray' file.yaml` where the expression yields a sequence/alias root; piping a JSON array into TOML output; selecting a list as the whole document.","commonSituations":"Converting YAML/JSON lists (e.g. dependency arrays, CI step lists) to TOML; filters like `.[]` or `map(...)` yielding sequences; expecting TOML to represent a top-level array like JSON does.","solutions":["Wrap the list in a map: `yq -o toml '{items: .}' file.yaml`.","If the source is a top-level array, key it first: `yq -o toml '{\"item0\": .[0], \"item1\": .[1]}'` or use to_entries-style transforms.","Keep the default `.` expression if the document root is already a mapping.","Use json/yaml output for array-root data."],"exampleFix":"# before\nyq -o toml '.deps' file.yaml   # deps is a list -> error\n\n# after\nyq -o toml '{\"deps\": .deps}' file.yaml   # wait: better -> yq -o toml '.' file.yaml (root map) or wrap: {deps: [...]}","handlingStrategy":"validation","validationCode":"[ \"$(yq 'kind' file.yaml)\" = \"mapping\" ] || echo \"TOML output needs a mapping root\"","typeGuard":"isTomlSafe() { [ \"$(yq 'kind' \"$1\")\" = \"mapping\" ]; }","tryCatchPattern":"yq -o toml '.' file.yaml || yq -o toml '{items: .}' file.yaml","preventionTips":["Wrap array roots in a keyed map before -o toml","Avoid filters that collapse the root to a sequence","Use json/yaml for array-shaped top-level data"],"tags":["toml","encoder","mapping","node-kind"],"backgroundTag":"unsupported-root-node-type","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"}