mikefarah/yq · error

configure YAML encoding

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.

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

• alias cycle detected
• cannot convert node at path
• cannot convert node value
• cannot index array with
• cannot multiply with

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

Appendix: 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)