{"record":{"id":"ea5c2264a3c0a1e2","repo":"hashicorp/nomad","slug":"acl-token-is-invalid","errorCode":null,"errorMessage":"ACL token is invalid","messagePattern":"ACL token is invalid","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/errors.go","lineNumber":58,"sourceCode":"\n\terrDeploymentTerminalNoCancel    = \"can't cancel terminal deployment\"\n\terrDeploymentTerminalNoFail      = \"can't fail terminal deployment\"\n\terrDeploymentTerminalNoPause     = \"can't pause terminal deployment\"\n\terrDeploymentTerminalNoPromote   = \"can't promote terminal deployment\"\n\terrDeploymentTerminalNoResume    = \"can't resume terminal deployment\"\n\terrDeploymentTerminalNoUnblock   = \"can't unblock terminal deployment\"\n\terrDeploymentTerminalNoRun       = \"can't run terminal deployment\"\n\terrDeploymentTerminalNoSetHealth = \"can't set health of allocations for a terminal deployment\"\n\terrDeploymentRunningNoUnblock    = \"can't unblock running deployment\"\n)\n\nvar (\n\tErrNoLeader                   = errors.New(errNoLeader)\n\tErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)\n\tErrNoRegionPath               = errors.New(errNoRegionPath)\n\tErrTokenNotFound              = errors.New(errTokenNotFound)\n\tErrTokenExpired               = errors.New(errTokenExpired)\n\tErrTokenInvalid               = errors.New(errTokenInvalid)\n\tErrPermissionDenied           = errors.New(errPermissionDenied)\n\tErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)\n\tErrNoNodeConn                 = errors.New(errNoNodeConn)\n\tErrUnknownMethod              = errors.New(errUnknownMethod)\n\tErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)\n\tErrNodeLacksRpc               = errors.New(errNodeLacksRpc)\n\tErrMissingAllocID             = errors.New(errMissingAllocID)\n\tErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)\n\tErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)\n\n\t// ErrResultPaginatorCreation is returned by list RPC handlers when the\n\t// result paginator cannot be built, for example when the server cannot\n\t// evaluate a requested filter expression. api.ResultPaginatorErrorContent\n\t// duplicates its message so the CLI can match it without importing structs.\n\t// Keep the two in sync.\n\tErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)\n\n\tErrUnknownNode = errors.New(ErrUnknownNodePrefix)","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L40-L76","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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"],"exampleFix":"// before\ntoken := \"my-agent-token\" // not a UUID -> ErrTokenInvalid\n// after\ntoken := \"0a9f7e99-0d80-81fe-d780-35a6769d8b13\" // valid UUID ACL token SecretID","handlingStrategy":"validation","validationCode":"if !helper.IsUUID(secretID) {\n    return fmt.Errorf(\"secret ID must be a UUID ACL token, got %q\", secretID)\n}","typeGuard":"func IsValidUUID(s string) bool {\n    _, err := uuid.Parse(s)\n    return err == nil\n}","tryCatchPattern":"_, err := client.ACL().Info(token)\nif errors.Is(err, structs.ErrTokenInvalid) {\n    // token absent or malformed: fail fast, prompt for a new token\n}","preventionTips":["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"],"tags":["acl","auth","nomad","invalid-token"],"backgroundTag":"acl-token-invalid","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}