Permission and Access Errors

Symptom

The editor, dashboard, or API returns a 401 (Unauthorized) or 403 (Forbidden) error. The UI may show "Access denied," redirect to the login page, or display a blank screen with an error toast.

Likely Causes

1. Session expired: Your authentication session has expired. Clerk sessions have a finite lifetime. Stale sessions return 401 on API requests.
2. Not a project member: You are trying to access a project that you do not own and have not been invited to.
3. Insufficient role: Your project role (viewer) does not permit the action (e.g., deploying requires an owner, admin, or member role).
4. Organization mismatch: You are viewing projects under an organization you are no longer a member of, or you have switched organizations and the project belongs to a different one.
5. Session cookie invalid: Your authentication session cookie has expired or been cleared.
6. Middleware rejection: The Next.js middleware checks authentication for all non-public API routes. If the session cookie is missing or invalid, the middleware returns 401 before the route handler runs.

Checks

1. Check the HTTP status code:
   • 401: Authentication failed. You are not logged in or your session has expired.
   • 403: Authorization failed. You are logged in but lack permission for the requested resource.
2. Open the browser's Network tab and inspect the failing request. Look at the response body for a specific error message (e.g., "error": "Access denied" or "error": "Unauthorized").
3. Verify you are logged in. Check the top-right of the dashboard for your profile avatar.
4. If accessing a shared project, verify your membership. Ask the project owner to check the Members tab in project settings.
5. If using the API directly, verify the authentication token is present in the request headers and has not expired.

Fixes

Session expired (401)

1. Reload the page. If the session has expired, you will be redirected to the login page.
2. Log in again. A new session is created.
3. Navigate back to the page you were on.

Not a project member (403)

1. Ask the project owner to invite you from the project's Members tab.
2. Accept the invite via the email link or notification.
3. Reload the project page.

Insufficient role (403)

1. Check your role in the project's Members tab: owner, editor, or viewer.
2. If you need a higher role (e.g., editor to deploy), ask the project owner to update your role.
3. Note: only owner, admin, and member roles can deploy, edit files, and hold edit control. Viewer role is read-only. See Team Collaboration.

Organization mismatch

1. Open the organization switcher in the dashboard sidebar.
2. Switch to the organization that owns the project.
3. If you are no longer a member of that organization, ask an organization admin to re-invite you.

What to Capture for Escalation

1. The HTTP status code (401 or 403).
2. The full URL of the failing request.
3. The response body from the Network tab.
4. Your user email and the project ID or slug.
5. Your role on the project (if known): owner, admin, member, or viewer.
6. Whether the issue reproduces after logging out and back in.