hashicorp/nomad · error

Error querying node: %w

Error message

Error querying node: %w

What it means

lookupNodeID calls client.PrefixList(nodeID) to find nodes whose ID matches the given prefix. If that API call returns an error (network failure, permission denied, server error), the error is wrapped as "Error querying node: %w" and returned for display. The wrapped cause (%w) carries the underlying API error.

Source

Thrown at command/node.go:86

		if k != "" {
			rows = append(rows, fmt.Sprintf("%s|%s", k, meta[k]))
		}
	}

	return formatKV(rows)
}

// 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. Read the wrapped cause after the colon for the root error.
2. Verify NOMAD_ADDR points to a live Nomad agent: `nomad server members` or `curl $NOMAD_ADDR/v1/agent/health`.
3. Check ACL token validity/permissions (node:read capability): `nomad acl token info <id>`.
4. If TLS is configured, verify CA cert / client cert settings.

Example fix

// before (shell)
NOMAD_ADDR=http://localhost:4600 nomad node status abc   // wrong port
// after
NOMAD_ADDR=http://localhost:4646 nomad node status abc

// shell: check connectivity first
curl -fsS "$NOMAD_ADDR/v1/agent/health" >/dev/null || { echo "nomad unreachable at $NOMAD_ADDR"; exit 1; }

// bash: inspect wrapped cause
if ! out=$(nomad node status "$ID" 2>&1); then
  case "$out" in
    *"Error querying node"*) echo "API failure: ${out#*Error querying node: }" ;;
  esac
fi

When it happens

Trigger: Any command resolving a node ID prefix (e.g. `nomad node status <prefix>`) when the PrefixList API request fails: unreachable NOMAD_ADDR, invalid ACL token, TLS problems, or Nomad server errors.

Common situations: Nomad agent not running or wrong NOMAD_ADDR; expired/insufficient ACL token lacking node:read; TLS/misconfigured certificates; network partitions between client and cluster.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• http addr of node %q (%s) is not advertised
• Node ID must contain at least two characters.
• No node(s) with prefix or id %q found
• Prefix matched multiple nodes\n\n%s
• network address family must be one of: "", %q, %q

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