hashicorp/nomad · error · ErrUnknownAllocationPrefix

%s %q

Error message

%s %q

What it means

NewErrUnknownAllocation builds the sentinel-style error signaling that the client does not know the referenced allocation (e.g. it is not running on that node); RPC/streaming handlers use it so callers can distinguish unknown allocs via IsErrUnknownAllocation.

Source

Thrown at nomad/structs/errors.go:137

// the given node.
func IsErrNoNodeConn(err error) bool {
	return err != nil && strings.Contains(err.Error(), errNoNodeConn)
}

// IsErrUnknownMethod returns whether the error is due to the operation not
// being allowed due to lack of permissions.
func IsErrUnknownMethod(err error) bool {
	return err != nil && strings.Contains(err.Error(), errUnknownMethod)
}

func IsErrRPCCoded(err error) bool {
	return err != nil && strings.HasPrefix(err.Error(), errRPCCodedErrorPrefix)
}

// NewErrUnknownAllocation returns a new error caused by the allocation being
// unknown.
func NewErrUnknownAllocation(allocID string) error {
	return fmt.Errorf("%s %q", ErrUnknownAllocationPrefix, allocID)
}

// NewErrUnknownNode returns a new error caused by the node being unknown.
func NewErrUnknownNode(nodeID string) error {
	return fmt.Errorf("%s %q", ErrUnknownNodePrefix, nodeID)
}

// NewErrUnknownJob returns a new error caused by the job being unknown.
func NewErrUnknownJob(jobID string) error {
	return fmt.Errorf("%s %q", ErrUnknownJobPrefix, jobID)
}

// NewErrUnknownEvaluation returns a new error caused by the evaluation being
// unknown.
func NewErrUnknownEvaluation(evaluationID string) error {
	return fmt.Errorf("%s %q", ErrUnknownEvaluationPrefix, evaluationID)
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the allocation ID exists and is assigned to the targeted client
2. Refresh allocation state from the server before retrying
3. Treat as non-retryable for that client and clean up stale references

When it happens

Trigger: Thrown at nomad/structs/errors.go:137 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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