{"record":{"id":"5497302c45e8d49b","repo":"mikefarah/yq","slug":"lua-global-requires-a-top-level-mappingnode","errorCode":null,"errorMessage":"--lua-global requires a top level MappingNode","messagePattern":"--lua-global requires a top level MappingNode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/encoder_lua.go","lineNumber":329,"sourceCode":"}\n\nfunc (le *luaEncoder) encodeTopLevel(writer io.Writer, node *CandidateNode) error {\n\terr := writeString(writer, le.docPrefix)\n\tif err != nil {\n\t\treturn err\n\t}\n\terr = le.encodeAny(writer, node)\n\tif err != nil {\n\t\treturn err\n\t}\n\treturn writeString(writer, le.docSuffix)\n}\n\nfunc (le *luaEncoder) Encode(writer io.Writer, node *CandidateNode) error {\n\n\tif le.globals {\n\t\tif node.Kind != MappingNode {\n\t\t\treturn fmt.Errorf(\"--lua-global requires a top level MappingNode\")\n\t\t}\n\t\treturn le.encodeMap(writer, node, true)\n\t}\n\treturn le.encodeTopLevel(writer, node)\n}\n","sourceCodeStart":311,"sourceCodeEnd":335,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/encoder_lua.go#L311-L335","documentation":"With `--lua-global` (or `-o lua --lua-global`), the Lua encoder emits each top-level key as a global variable (`key = value`). That only makes sense for a top-level map, so Encode rejects any other root Kind (scalar, sequence) with this message.","triggerScenarios":"Running `yq --output-format lua --lua-global '.' file.yaml` where the root document is an array or the expression evaluates to a scalar/sequence instead of a mapping.","commonSituations":"Converting a JSON/YAML array config to Lua globals; a filter like `.[]` that yields multiple scalars; piping results of `keys` or similar list-yielding expressions to Lua global output.","solutions":["Make the expression produce a map: `yq -o lua --lua-global '{key: .}'`.","If the root is an array, transform it into a map keyed by index or name first: `with_entries` / map-to-object style transforms.","Drop `--lua-global` so output uses the default `return {...}` table form, which accepts any top-level structure.","Select the mapping sub-document you actually want, e.g. `.myConfig`."],"exampleFix":"# before\nyq -o lua --lua-global '.[]' list.yaml   # yields scalars/sequence\n\n# after\nyq -o lua --lua-global '.' list.yaml   # root is a map; or drop --lua-global","handlingStrategy":"validation","validationCode":"[ \"$(yq 'kind' file.yaml)\" = \"mapping\" ] || echo \"--lua-global needs a map root\"","typeGuard":"isLuaGlobalSafe() { [ \"$(yq 'kind' \"$1\")\" = \"mapping\" ]; }","tryCatchPattern":"yq -o lua --lua-global '.' file.yaml || yq -o lua '{root: .}' file.yaml","preventionTips":["Only pass --lua-global when the document root is a mapping","Prefer default table output (`return {...}`) for unknown shapes","Convert array roots to maps before using globals mode"],"tags":["lua","encoder","globals","mapping"],"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"}