mikefarah/yq · error

orderedMap: invalid yaml node

Error message

orderedMap: invalid yaml node

What it means

CandidateNode.UnmarshalYAML copies a yaml.Node (from gopkg.in/yaml.v3) into a CandidateNode by switching on the node Kind (document/mapping/sequence/alias/scalar, and 0 as a degenerate case). Any Kind value outside the known yaml.Kind set reaches the default branch and yields 'orderedMap: invalid yaml node'. It means the YAML library handed back a node kind yq does not recognise.

Source

Thrown at pkg/yqlib/candidate_node_yaml.go:174

			keyNode.Kind = ScalarNode
			keyNode.Value = fmt.Sprintf("%v", i)

			valueNode, err := o.decodeIntoChild(node.Content[i], anchorMap)
			if err != nil {
				return err
			}

			valueNode.Key = keyNode
			o.Content[i] = valueNode
		}
		return nil
	case 0:
		// not sure when this happens
		o.copyFromYamlNode(node, anchorMap)
		log.Debugf("UnmarshalYAML -  err.. %v", NodeToString(o))
		return nil
	default:
		return fmt.Errorf("orderedMap: invalid yaml node")
	}
}

func (o *CandidateNode) MarshalYAML() (*yaml.Node, error) {
	log.Debugf("MarshalYAML to yaml: %v", o.Tag)
	switch o.Kind {
	case AliasNode:
		log.Debugf("MarshalYAML - alias to yaml: %v", o.Tag)
		target := &yaml.Node{Kind: yaml.AliasNode}
		o.copyToYamlNode(target)
		return target, nil
	case ScalarNode:
		log.Debugf("MarshalYAML - scalar: %v", o.Value)
		target := &yaml.Node{Kind: yaml.ScalarNode}
		o.copyToYamlNode(target)
		return target, nil
	case MappingNode, SequenceNode:
		targetKind := yaml.MappingNode

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Check your gopkg.in/yaml.v3 version matches what yq's go.mod expects (`go mod tidy` / `go get gopkg.in/yaml.v3@<version>`) — a Kind mismatch is almost always a dependency drift.
2. If constructing yaml.Node values in Go, set Kind to a valid yaml.v3 kind (DocumentNode/SequenceNode/MappingNode/ScalarNode/AliasNode) before decoding.
3. Validate that any custom yaml.Node → yq bridges (custom UnmarshalYAML) return well-formed nodes; log node.Kind when reproducing.
4. Upgrade yq to the latest release, which tracks compatible yaml.v3 versions.

Example fix

// before: manually built node with zero Kind
node := &yaml.Node{Value: "hi"} // Kind==0 or invalid → invalid yaml node
// after
node := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: "hi"}

// Go: check the yaml.Node kind before handing it to yq
func isKnownYamlKind(n *yaml.Node) bool {
    switch n.Kind {
    case yaml.DocumentNode, yaml.SequenceNode, yaml.MappingNode,
        yaml.ScalarNode, yaml.AliasNode, 0:
        return true
    }
    return false
}

if !isKnownYamlKind(node) {
    return fmt.Errorf("unsupported yaml node kind %d", node.Kind)
}

// Go
if err := candidate.UnmarshalYAML(node); err != nil {
    if strings.Contains(err.Error(), "invalid yaml node") {
        return inspectAndRepairNode(node) // log node.Kind, rebuild valid node
    }
    return err
}

When it happens

Trigger: Decoding YAML into CandidateNode where the underlying yaml.Node has an unexpected Kind — effectively only possible with a yaml library version introducing a new Kind, or corrupted/programmatically constructed yaml.Node values passed to Decode.

Common situations: Version mismatch between yq and gopkg.in/yaml.v3 (new Kind constant added upstream); Go code that builds yaml.Node structs manually with a zero-or-invalid Kind and feeds them to yq's decoder; nested custom UnmarshalYAML implementations returning malformed nodes.

Related errors

• unrecognised type :( %v
• no support for input format
• aborted
• unknown operator %v
• cannot multiply %v with %v

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