hashicorp/nomad · error

Prefix matched multiple nodes\n\n%s

Error message

Prefix matched multiple nodes\n\n%s

What it means

If PrefixList returns more than one node for the given prefix and none exactly equals the input, lookupNodeID refuses to guess and returns "Prefix matched multiple nodes" followed by a formatted table of candidate node stubs (formatted via formatNodeStubList). It asks the user to supply a longer prefix.

Source

Thrown at command/node.go:94

// lookupNodeID looks up a nodeID prefix and returns the full ID or an error.
// The error will always be suitable for displaying to users.
func lookupNodeID(client *api.Nodes, nodeID string) (string, error) {
	if len(nodeID) == 1 {
		return "", fmt.Errorf("Node ID must contain at least two characters.")
	}

	nodeID = sanitizeUUIDPrefix(nodeID)
	nodes, _, err := client.PrefixList(nodeID)
	if err != nil {
		return "", fmt.Errorf("Error querying node: %w", err)
	}

	if len(nodes) == 0 {
		return "", fmt.Errorf("No node(s) with prefix or id %q found", nodeID)
	}

	if len(nodes) > 1 {
		return "", fmt.Errorf("Prefix matched multiple nodes\n\n%s",
			formatNodeStubList(nodes, true))
	}

	return nodes[0].ID, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Extend the prefix using characters from the candidate list printed with the error.
2. Use the full 36-character node UUID to be unambiguous.
3. In scripts, pick IDs programmatically (e.g. from `nomad node status -json` filtered by name/datacenter) instead of short prefixes.
4. Add `-node-class` or filter by datacenter if your tooling supports it.

Example fix

// before (shell)
nomad node status a1    # ambiguous
// after
nomad node status a1b2c3d4-5678-90ab-cdef-1234567890ab

// shell: require a long, unambiguous prefix
[ ${#NODE_ID} -ge 8 ] || { echo "use at least 8 chars of the node UUID"; exit 1; }
nomad node status "$NODE_ID"

// bash: use the candidate list in the error to disambiguate
if ! out=$(nomad node status "$ID" 2>&1); then
  case "$out" in *"matched multiple nodes"*) echo "$out" ;; esac
fi

When it happens

Trigger: Calling `nomad node status <prefix>` where the prefix matches 2+ node IDs and the input is not itself an exact node ID.

Common situations: Very short prefixes in homogeneous clusters (nodes provisioned by the same tooling share ID prefixes); copy-pasting only a few ID characters; scripted ID selection that truncates IDs too aggressively.

Related errors

• Node ID must contain at least two characters.
• Error querying node: %w
• No node(s) with prefix or id %q found
• A template must be supplied using '-template' when using go-
• Invalid value for "-out"; valid values are [go-template, hcl

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/0dd6f775b25a804c. Report an issue: GitHub.