What causes "ACL token is invalid" in hashicorp/nomad?

Verify the token is a valid UUID format before configuring it

ACL token is invalid

Error message

ACL token is invalid

What it means

ErrTokenInvalid is a sentinel error meaning the presented ACL token does not exist or is malformed. resolveSecretToken rejects any SecretID that is not a UUID outright, and authentication fails with this error when the token cannot be resolved to a valid ACL entry. VerifyClaim may then be attempted for non-UUID secrets as identity claims.

Source

Thrown at nomad/structs/errors.go:58

	errDeploymentTerminalNoCancel    = "can't cancel terminal deployment"
	errDeploymentTerminalNoFail      = "can't fail terminal deployment"
	errDeploymentTerminalNoPause     = "can't pause terminal deployment"
	errDeploymentTerminalNoPromote   = "can't promote terminal deployment"
	errDeploymentTerminalNoResume    = "can't resume terminal deployment"
	errDeploymentTerminalNoUnblock   = "can't unblock terminal deployment"
	errDeploymentTerminalNoRun       = "can't run terminal deployment"
	errDeploymentTerminalNoSetHealth = "can't set health of allocations for a terminal deployment"
	errDeploymentRunningNoUnblock    = "can't unblock running deployment"
)

var (
	ErrNoLeader                   = errors.New(errNoLeader)
	ErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)
	ErrNoRegionPath               = errors.New(errNoRegionPath)
	ErrTokenNotFound              = errors.New(errTokenNotFound)
	ErrTokenExpired               = errors.New(errTokenExpired)
	ErrTokenInvalid               = errors.New(errTokenInvalid)
	ErrPermissionDenied           = errors.New(errPermissionDenied)
	ErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)
	ErrNoNodeConn                 = errors.New(errNoNodeConn)
	ErrUnknownMethod              = errors.New(errUnknownMethod)
	ErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)
	ErrNodeLacksRpc               = errors.New(errNodeLacksRpc)
	ErrMissingAllocID             = errors.New(errMissingAllocID)
	ErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)
	ErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)

	// ErrResultPaginatorCreation is returned by list RPC handlers when the
	// result paginator cannot be built, for example when the server cannot
	// evaluate a requested filter expression. api.ResultPaginatorErrorContent
	// duplicates its message so the CLI can match it without importing structs.
	// Keep the two in sync.
	ErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)

	ErrUnknownNode = errors.New(ErrUnknownNodePrefix)

View on GitHub (pinned to 482b49bf1a)

Solutions

Verify the token is a valid UUID format before configuring it
Re-list tokens with 'nomad acl token list' to confirm the token exists in this cluster
Re-create the token if it was deleted, and update the client/agent config
Check you are pointing at the correct cluster address/region

Example fix

// before
token := "my-agent-token" // not a UUID -> ErrTokenInvalid
// after
token := "0a9f7e99-0d80-81fe-d780-35a6769d8b13" // valid UUID ACL token SecretID

Defensive patterns

Strategy: validation

Validate before calling

if !helper.IsUUID(secretID) {
    return fmt.Errorf("secret ID must be a UUID ACL token, got %q", secretID)
}

Type guard

func IsValidUUID(s string) bool {
    _, err := uuid.Parse(s)
    return err == nil
}

Try / catch

_, err := client.ACL().Info(token)
if errors.Is(err, structs.ErrTokenInvalid) {
    // token absent or malformed: fail fast, prompt for a new token
}

Prevention

Validate token format (UUID) at config-load time
Confirm the token exists in the target cluster before deploying clients
Avoid hand-copying tokens; fetch them programmatically from a secret store
Pin cluster address/region so tokens are used where they were issued

When it happens

Trigger: Passing a SecretID that is not a UUID to resolveSecretToken (nomad/auth/auth.go:877), or resolving a SecretID that no longer corresponds to any stored ACL token via Authenticate/resolveSecretToken.

Common situations: Typo or truncation of a token when copying it into config; connecting to a different cluster/region than the one that issued the token; token deleted after being written into a client config; passing a JWT/identity claim to an endpoint expecting a UUID token (before claim verification kicks in).

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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