{"record":{"id":"8b54e72ea9429dc6","repo":"n8n-io/n8n","slug":"user-is-missing-a-scope-required-to-perform-this-a","errorCode":null,"errorMessage":"User is missing a scope required to perform this action","messagePattern":"User is missing a scope required to perform this action","errorType":"http","errorClass":null,"httpStatus":403,"severity":"warning","filePath":"packages/cli/src/controller.registry.ts","lineNumber":245,"sourceCode":"\t\treturn (_req, res, next) => {\n\t\t\tif (!this.license.isLicensed(feature)) {\n\t\t\t\tres.status(403).json({ status: 'error', message: 'Plan lacks license for this feature' });\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tnext();\n\t\t};\n\t}\n\n\tprivate createScopedMiddleware(accessScope: AccessScope): RequestHandler {\n\t\treturn async (req, res, next) => {\n\t\t\tif (!isAuthenticatedRequest(req)) throw new UnauthenticatedError();\n\t\t\tif (!req.user) throw new UnauthenticatedError();\n\n\t\t\tconst { scope, globalOnly } = accessScope;\n\n\t\t\ttry {\n\t\t\t\tif (!(await userHasScopes(req.user, [scope], globalOnly, req.params))) {\n\t\t\t\t\tres.status(403).json({\n\t\t\t\t\t\tstatus: 'error',\n\t\t\t\t\t\tmessage: RESPONSE_ERROR_MESSAGES.MISSING_SCOPE,\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t} catch (error) {\n\t\t\t\tif (error instanceof NotFoundError) {\n\t\t\t\t\tres.status(404).json({ status: 'error', message: error.message });\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\n\t\t\tnext();\n\t\t};\n\t}\n}\n","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/cli/src/controller.registry.ts#L227-L263","documentation":"Returned as a 403 JSON response by `createScopedMiddleware` when `userHasScopes(req.user, [scope], globalOnly, req.params)` resolves to false. The body is `{ status: 'error', message: RESPONSE_ERROR_MESSAGES.MISSING_SCOPE }` ('User is missing a scope required to perform this action'). The user is authenticated but lacks the specific RBAC scope required by the route.","triggerScenarios":"A non-admin user calls an endpoint that requires `user:list` or `project:edit`; a project member without owner role calls an owner-only endpoint; a global-only endpoint called by a project-scoped user.","commonSituations":"Role downgraded after permission change; new endpoint added with a scope the user's role does not include; cross-project access attempted by a member of a different project.","solutions":["Have an owner/admin assign the required role or scope to the user.","Re-authenticate so the updated scopes are loaded into the session.","If calling the Public API, use an API key whose role includes the needed scope.","Confirm `globalOnly` semantics — some scopes require a global admin role."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const required = ['user:list'];\nif (!await userHasScopes(currentUser, required, false, {})) {\n  throw new Error(`User missing scopes: ${required.join(', ')}`);\n}","typeGuard":null,"tryCatchPattern":"try { await api.get('/admin/users'); } catch (e) { if (e.response?.status === 403) { requestScopeUpgrade(); } else throw e; }","preventionTips":["Check the user's role/scopes before showing gated UI actions.","Refresh the user's session after role changes so scopes are current."],"tags":["api","rbac","rest","authorization","user-error"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}