> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budecosystem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common user management, RBAC, and authentication issues

<Note>
  Use this guide to quickly diagnose invitation failures, permission mismatches, and authentication/session issues.
</Note>

## Triage Flow

```mermaid theme={null}
flowchart TD
    A[Issue Reported] --> B{Login Fails?}
    B -->|Yes| C[Check credentials, account status, token refresh]
    B -->|No| D{Access Denied?}
    D -->|Yes| E[Check global scopes and project scopes]
    D -->|No| F[Check UI cache/session and backend logs]
```

## Invitation Issues

### User stays in `invited`

**Cause**: User has not completed initial login and password setup.

**Fix**:

1. Resend invitation.
2. Confirm email delivery path and spam filtering.
3. Validate account is not deactivated.

### Invite created but wrong role/scopes

**Cause**: Incorrect role selected during creation.

**Fix**:

1. Open user details.
2. Update role and permissions.
3. Re-test with a clean session.

## Permission Issues

### User cannot access a module

**Cause**: Missing `resource:view` or `resource:manage` scope.

**Fix**:

1. Check assigned global scopes.
2. Add missing scope.
3. Ask user to refresh session/sign in again.

### User can open project but cannot modify resources

**Cause**: Project-level permission is `view` only.

**Fix**: Upgrade project permission to `manage` if justified.

## Authentication Issues

### Repeated sign-out or session loops

**Cause**: Access token expiry plus refresh failure.

**Fix**:

1. Confirm refresh token endpoint health.
2. Verify local token storage is intact.
3. Clear local session and re-authenticate.

### 401/403 after role update

**Cause**: Old token still carries previous claims.

**Fix**: Force logout/login to refresh effective permissions.

## Operational Best Practices

<Check>Keep privileged scopes minimal and time-bound.</Check>
<Check>Review inactive and invited users on a schedule.</Check>
<Check>Use explicit project sharing instead of broad global manage scopes.</Check>