mikefarah/yq · error

cannot index array with '%v' (%w)

Error message

cannot index array with '%v' (%w)

What it means

When traversing an array with an index, yq parses the index string to an integer. If the index cannot be parsed as a number and the traversal is not optional (`?.`), it fails with 'cannot index array with ...'. The underlying parse error is wrapped (%w).

Source

Thrown at pkg/yqlib/operator_traverse_path.go:219

	var newMatches = list.New()
	if len(indices) == 0 {
		log.Debug("splatting")
		var index int
		for index = 0; index < len(node.Content); index = index + 1 {
			newMatches.PushBack(node.Content[index])
		}
		return newMatches, nil

	}

	for _, indexNode := range indices {
		log.Debugf("traverseArrayWithIndices: '%v'", indexNode.Value)
		index, err := parseInt(indexNode.Value)
		if err != nil && prefs.OptionalTraverse {
			continue
		}
		if err != nil {
			return nil, fmt.Errorf("cannot index array with '%v' (%w)", indexNode.Value, err)
		}
		indexToUse := index
		contentLength := len(node.Content)
		for contentLength <= index {
			if contentLength == 0 {
				// default to nice yaml formatting
				node.Style = 0
			}

			valueNode := createScalarNode(nil, "null")
			node.AddChild(valueNode)
			contentLength = len(node.Content)
		}

		if indexToUse < 0 {
			indexToUse = contentLength + indexToUse
		}

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Correct the expression so the index is an integer, e.g. `.a[0]` instead of `.a[foo]`
2. Use optional traverse `.[?]`-style syntax if you want non-numeric indexes to be skipped instead of erroring
3. If the intent is key lookup, verify the node is a map, not an array — reorder or add a type check in your expression, e.g. `select(type == "seq")`
4. Convert the value to a number first, e.g. `.a[($i | tonumber)]`

Example fix

// before
yq '.items[foo]' file.yaml
// after
yq '.items[0]' file.yaml

// Ensure the index is a valid integer before building the path
i, err := strconv.Atoi(idx)
if err != nil {
	return fmt.Errorf("array index %q is not an integer", idx)
}

func isArray(node *yaml.Node) bool { return node != nil && node.Kind == yaml.SequenceNode }
func isIntLiteral(s string) bool { _, err := strconv.Atoi(s); return err == nil }

out, err := yqEval(".a[0]", doc)
if err != nil && strings.Contains(err.Error(), "cannot index array") {
	// handle non-numeric index: fall back to key lookup or skip
}

When it happens

Trigger: Expressions like `.a[foo]` or `.a["1x"]` where the supplied index token is not a valid integer and the path is not an optional traverse; also calling traverseArrayWithIndices via the API with a non-numeric indexNode.Value.

Common situations: Typo in an index expression, accidentally quoting an index, interpolating a variable that contains a non-numeric string, or using object-key syntax against an array node.

Related errors

• index [%v] out of range, array size is %v
• yaml node has no content
• orderedMap: invalid yaml node
• INI encoder supports only MappingNode at the root level, got
• configure YAML encoding: %w

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