mikefarah/yq · error

unsupported array item kind: %v

Error message

unsupported array item kind: %v

What it means

writeArrayAttribute (multiline array branch) only supports scalar, sequence and mapping elements; any other node kind (e.g. an alias node that slipped past its own case, or an unexpected kind) hits the default branch. The %v is the numeric CandidateNode Kind. It indicates the array contains an element kind the TOML encoder cannot represent.

Source

Thrown at pkg/yqlib/encoder_toml.go:337

			switch it.Kind {
			case ScalarNode:
				itemStr = te.formatScalar(it)
			case SequenceNode:
				nested, err := te.sequenceToInlineArray(it)
				if err != nil {
					return err
				}
				itemStr = nested
			case MappingNode:
				inline, err := te.mappingToInlineTable(it)
				if err != nil {
					return err
				}
				itemStr = inline
			case AliasNode:
				return fmt.Errorf("aliases are not supported in TOML")
			default:
				return fmt.Errorf("unsupported array item kind: %v", it.Kind)
			}

			// Always add trailing comma in multiline arrays
			itemStr += ","

			if _, err := w.Write([]byte("  " + itemStr + "\n")); err != nil {
				return err
			}

			// Add blank line between elements (except after the last one)
			if i < len(seq.Content)-1 {
				if _, err := w.Write([]byte("\n")); err != nil {
					return err
				}
			}
		}

		if _, err := w.Write([]byte("]\n")); err != nil {

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Inspect the array contents (yq '.' input) and remove/replace the non-scalar element.
2. Derefence any aliases first: yq -o json then back to toml.
3. Ensure every array element is a concrete scalar, array, or table in the source YAML.
4. If using yqlib programmatically, normalize the tree (call UnwrapAliased or evaluate) before encoding.

Example fix

// before
a: # comment
  - null-ish-node   # unsupported kind
// after
a: # comment
  - "explicit value"   # scalar element

yq '[.. | kind] | any(. != "scalar" and . != "seq" and . != "map" and . != "alias")' in.yaml

// Go
func encodableKind(k yqlib.Kind) bool {
    switch k { case yqlib.ScalarNode, yqlib.SequenceNode, yqlib.MappingNode: return true }
    return false
}

// Go
if err := enc.EncodeTOML(node); err != nil {
    if strings.Contains(err.Error(), "unsupported array item kind") {
        // inspect/normalize offending element then re-encode
    }
}

When it happens

Trigger: Calling the TOML encoder on a CandidateNode sequence whose element Kind is neither ScalarNode, SequenceNode, MappingNode nor AliasNode — e.g. a document/null-kind node or internal node kinds produced by unusual expressions — when the array is rendered in multiline (element-comment) form.

Common situations: Programmatic use of yqlib where a raw CandidateNode tree (not from a normal decode) is encoded to TOML; documents containing nulls or exotic nodes placed inside commented arrays.

Related errors

• aliases are not supported in TOML
• TOML encoder expects a mapping at the root level
• cannot encode TOML entry with empty path
• unsupported node kind for TOML: %v
• unsupported inline table value kind: %v

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