What causes "--lua-global requires a top level MappingNode" in mikefarah/yq?

Make the expression produce a map: `yq -o lua --lua-global '{key: .}'`.

--lua-global requires a top level MappingNode

Error message

--lua-global requires a top level MappingNode

What it means

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.

Source

Thrown at pkg/yqlib/encoder_lua.go:329

}

func (le *luaEncoder) encodeTopLevel(writer io.Writer, node *CandidateNode) error {
	err := writeString(writer, le.docPrefix)
	if err != nil {
		return err
	}
	err = le.encodeAny(writer, node)
	if err != nil {
		return err
	}
	return writeString(writer, le.docSuffix)
}

func (le *luaEncoder) Encode(writer io.Writer, node *CandidateNode) error {

	if le.globals {
		if node.Kind != MappingNode {
			return fmt.Errorf("--lua-global requires a top level MappingNode")
		}
		return le.encodeMap(writer, node, true)
	}
	return le.encodeTopLevel(writer, node)
}

View on GitHub (pinned to 8b5af0694b)

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`.

Example fix

# before
yq -o lua --lua-global '.[]' list.yaml   # yields scalars/sequence

# after
yq -o lua --lua-global '.' list.yaml   # root is a map; or drop --lua-global

Defensive patterns

Strategy: validation

Validate before calling

[ "$(yq 'kind' file.yaml)" = "mapping" ] || echo "--lua-global needs a map root"

Type guard

isLuaGlobalSafe() { [ "$(yq 'kind' "$1")" = "mapping" ]; }

Try / catch

yq -o lua --lua-global '.' file.yaml || yq -o lua '{root: .}' file.yaml

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mikefarah/yq@8b5af0694b (2026-09-05). Data as JSON: /api/errors/5497302c45e8d49b. Report an issue: GitHub.