{"record":{"id":"ad9f94c461e33043","repo":"hashicorp/nomad","slug":"permission-denied","errorCode":null,"errorMessage":"Permission denied","messagePattern":"Permission denied","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/errors.go","lineNumber":59,"sourceCode":"\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)\n","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L41-L77","documentation":"ErrPermissionDenied is the generic sentinel error for ACL authorization failures in Nomad. It is returned when an authenticated token simply lacks the required capability — for example when AllowAgentWrite fails on the agent endpoint (command/agent/agent_endpoint.go / client/agent_endpoint.go:41). It is distinct from invalid/expired tokens: the token is valid but insufficiently privileged.","triggerScenarios":"Calling an authenticated endpoint whose required ACL capability is not granted: e.g. agent write endpoints when aclObj.AllowAgentWrite() is false; any handler whose ResolveToken / policy evaluation yields a deny decision.","commonSituations":"Tokens created with read-only policies being used for write operations; a client agent endpoint hit by an unprivileged caller; test fixtures (TestClient_ACL_ResolveToken) deliberately using bad tokens to assert denial.","solutions":["Attach a policy granting the required capability (e.g. 'agent write', node/alloc write) to the token","Create a new token with the management policy for administrative operations","Inspect effective policy via 'nomad acl token inspect' / 'nomad acl policy info' to confirm capabilities","Ensure the request targets the right namespace/region the policy covers"],"exampleFix":"// before\nnomad acl token create -policy=read-only  // then attempt agent write -> ErrPermissionDenied\n// after\nnomad acl policy apply agent-write agent-write.hcl  // includes: agent { policy = \"write\" }\nnomad acl token create -policy=agent-write","handlingStrategy":"type-guard","validationCode":"// pre-check capability before the call\nif !aclObj.AllowAgentWrite() {\n    return errors.New(\"token lacks agent write capability\")\n}","typeGuard":"func IsPermissionDenied(err error) bool {\n    return errors.Is(err, structs.ErrPermissionDenied)\n}","tryCatchPattern":"err := doRequest()\nif errors.Is(err, structs.ErrPermissionDenied) {\n    // request a token with the required policy or surface a clear authz error\n}","preventionTips":["Grant least-privilege policies explicitly listing needed capabilities","Test tokens with 'nomad acl token inspect' before wiring into automation","Separate read and write tokens per workload","Keep namespace/region scopes in policies aligned with actual usage"],"tags":["acl","authorization","permissions","nomad"],"backgroundTag":"permission-denied","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"}