{"record":{"id":"132a6f438a703373","repo":"hashicorp/nomad","slug":"could-not-resolve-user-w","errorCode":null,"errorMessage":"could not resolve user: %w","messagePattern":"could not resolve user: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/auth/auth.go","lineNumber":187,"sourceCode":"\t\t\t\treturn fmt.Errorf(\"could not resolve node secret: %w\", err)\n\t\t\t}\n\t\t\tif node != nil {\n\t\t\t\targs.SetIdentity(&structs.AuthenticatedIdentity{ClientID: node.ID})\n\t\t\t\treturn nil\n\t\t\t}\n\t\t}\n\n\t\t// we were passed a bogus token so we'll return an error, but we'll also\n\t\t// want to capture the IP for metrics\n\t\tremoteIP, err := ctx.GetRemoteIP()\n\t\tif err != nil {\n\t\t\ts.logger.Error(\"could not determine remote address\", \"error\", err)\n\t\t}\n\t\targs.SetIdentity(&structs.AuthenticatedIdentity{RemoteIP: remoteIP})\n\t\treturn structs.ErrPermissionDenied\n\n\tdefault: // any other error\n\t\treturn fmt.Errorf(\"could not resolve user: %w\", err)\n\n\t}\n\n\t// If there's no context we're in a \"static\" handler which only happens for\n\t// cases where the leader is making RPCs internally (volumewatcher and\n\t// deploymentwatcher)\n\tif ctx.IsStatic() {\n\t\targs.SetIdentity(&structs.AuthenticatedIdentity{ACLToken: aclToken})\n\t\treturn nil\n\t}\n\n\t// At this point we either have an anonymous token or an invalid one.\n\n\t// Unlike clients that provide their Node ID on first connection, server\n\t// RPCs don't include an ID for the server so we identify servers by cert\n\t// and IP address.\n\tidentity := &structs.AuthenticatedIdentity{ACLToken: aclToken}\n\tif ctx.IsTLS() {","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/auth/auth.go#L169-L205","documentation":"When resolving an ACL token via the auth method fails with any error other than permission-denied/not-found style cases, Authenticate wraps it as 'could not resolve user'. This means the token lookup against the token store returned an unexpected internal error, distinct from an outright permission denial.","triggerScenarios":"An RPC arrives with a bearer/ACL token; Authenticate calls the ACL resolver and the resolution returns a non-permission error (e.g. store failure, leader not ready), hitting the `default:` branch of the error switch.","commonSituations":"ACL state store hiccup on the server; request processed before leader/ACL state fully initialized; transient Raft unavailability during token lookup.","solutions":["Read the wrapped cause (`%w`) in the server log to identify the underlying resolution error","Retry the RPC — transient leader/state issues typically resolve once the cluster settles","Verify cluster health (`nomad server members`, leader election) and ACL subsystem status","If persistent, check the ACL token store integrity / restore from snapshot"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"could not resolve user\") {\n    // transient resolution error: retry with backoff after leader settles\n    retryWithBackoff()\n}","preventionTips":["Verify ACL subsystem is enabled/healthy before issuing client RPCs","Confirm cluster leader stability (`nomad server members`) during upgrades","Retry transient auth resolution failures with exponential backoff"],"tags":["nomad","authentication","acl","rpc"],"backgroundTag":"acl-token-resolution-failed","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"}