mikefarah/yq · error

configure YAML encoding: %w

Error message

configure YAML encoding: %w

What it means

Returned by the YAML encoder when the underlying go-yaml dumper cannot be configured (e.g. invalid indent, unsupported options). It wraps the low-level yaml.WriteOption error with the 'configure YAML encoding' prefix so callers know the failure happened before any node was serialized. Nothing was written yet when this fires.

Source

Thrown at pkg/yqlib/encoder_yaml.go:67

	if ye.prefs.ColorsEnabled {
		destination = tempBuffer
	}

	indent := ye.prefs.Indent
	if indent < 2 {
		indent = 2
	} else if indent > 9 {
		indent = 9
	}

	dumper, err := yaml.NewDumper(destination,
		yaml.WithV3Defaults(),
		yaml.WithIndent(indent),
		yaml.WithCompactSeqIndent(ye.prefs.CompactSequenceIndent),
		yaml.WithLineWidth(-1),
	)
	if err != nil {
		return fmt.Errorf("configure YAML encoding: %w", err)
	}

	target, err := node.MarshalYAML()
	if err != nil {
		_ = dumper.Close()
		return err
	}

	trailingContent := target.FootComment
	target.FootComment = ""

	err = dumper.Dump(target)
	if closeErr := dumper.Close(); err == nil {
		err = closeErr
	}
	if err != nil {
		return err
	}

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Use a supported indent value (typically 2 or 4, must be > 0) via --indent or the encoder preferences
2. Inspect the wrapped %w cause to identify which With* option was rejected
3. If embedding yqlib, validate preferences (Indent, CompactSequenceIndent) before calling NewYamlEncoder/Encode

Example fix

// before
yq -o yaml --indent 0 '.' file.yml
// after
yq -o yaml --indent 2 '.' file.yml

indent := 2 // must be > 0; validate before invoking yq/yqlib
if indent <= 0 {
    return fmt.Errorf("invalid indent %d for YAML encoder", indent)
}

func validIndent(n int) bool { return n > 0 }

out, err := enc.Encode(node)
if err != nil {
    var cfgErr interface{ Unwrap() error }
    if errors.As(err, &wrapped) && strings.Contains(err.Error(), "configure YAML encoding") {
        // fix encoder preferences and retry
    }
    return err
}

When it happens

Trigger: Calling yq with an encoding setup whose yaml encoder options are invalid — e.g. a non-positive or oversized --indent value passed to NewYamlEncoder preferences causing yaml.WithIndent(indent) to fail inside Encode.

Common situations: Users invoking `yq -o yaml --indent 0` or a harness passing indent from config/env where the value is 0 or negative; embedding yqlib with custom encoder preferences that the bundled go-yaml build rejects.

Related errors

• yaml node has no content
• orderedMap: invalid yaml node
• csv object encoding only works for arrays of flat objects (s
• csv object encoding only works for arrays of flat objects (s
• csv encoding only works for arrays, got: %v

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