Troubleshooting Roles & Permissions

This guide covers common issues you may encounter when working with roles and permissions in Rahal.

Permission Issues

User Cannot Access a Feature

Symptom: User sees "403 Forbidden" or feature is not visible in the dashboard.

Diagnosis:

1. Check what permission the feature requires
2. Check the user's assigned role
3. Verify the role includes that permission

Solutions:

User Has Permission But Feature Still Hidden

Symptom: Role has the permission, but user can't access the feature.

Diagnosis:

1. Have user log out and log back in
2. Clear browser cache
3. Check if feature requires multiple permissions

Common multi-permission requirements:

Permission Change Not Taking Effect

Symptom: Role permissions were changed but user still has old access.

Diagnosis:

1. Verify the role was saved successfully
2. Check user is assigned the modified role
3. Have user refresh the page

Solutions:

• Refresh the browser (F5 or Cmd+R)
• Log out and log back in
• Clear browser cache if problem persists
• Verify the change in the database

Role Creation Issues

"Role with code already exists"

Symptom: Error when creating a role with a name similar to an existing role.

Cause: Role codes are generated from names and must be unique per company.

Solutions:

Example code conflicts:

"Reserved code" Error

Symptom: Error when using names that generate reserved codes.

Cause: MEMBER, MANAGER, ADMIN are reserved for predefined roles.

Examples of problematic names:

• "Member" → MEMBER (reserved)
• "Manager" → MANAGER (reserved)
• "Admin" → ADMIN (reserved)
• "System Admin" → SYSTEM_ADMIN (allowed)

Solutions:

• Use more descriptive names: "Team Member", "Department Manager", "Company Admin"
• Add prefixes or suffixes to avoid reserved codes

"At least one permission is required"

Symptom: Cannot save role without permissions selected.

Cause: Every role must have at least one permission.

Solution: Select at least one permission from the permission matrix before saving.

Role Deletion Issues

"Cannot delete role: X users are currently assigned"

Symptom: Cannot delete a custom role because users are assigned to it.

Diagnosis:

1. Note the number of users mentioned
2. Find these users in the Users list
3. Reassign them to different roles

Solution:

1. Go to Users
2. Filter or search for users with the role
3. Edit each user and assign a different role
4. Return to Roles and retry deletion

"Predefined roles cannot be deleted"

Symptom: Delete button missing or error when trying to delete Member, Manager, or Admin.

Cause: Predefined roles are permanent and cannot be deleted.

Workaround: If you don't want to use a predefined role:

• Simply don't assign users to it
• Create custom roles for your needs
• Predefined roles won't affect users not assigned to them

Role Assignment Issues

Cannot Find Role in Dropdown

Symptom: When editing a user, expected role is not in the dropdown.

Possible causes:

"Role does not belong to this company"

Symptom: Error when trying to assign a role to a user.

Cause: Roles are company-scoped; you're trying to assign a role from a different company.

Solution:

1. Verify you're editing a user in the correct company
2. Verify you're selecting a role from the correct company
3. Check your company context in the dashboard

User Has Wrong Permissions Despite Role

Symptom: User's access doesn't match their assigned role.

Diagnosis:

1. Check the user's actual role assignment (not assumed)
2. Check the role's actual permissions
3. Verify no database-level overrides

Common mistakes:

• Assuming role from email domain (roles must be explicitly assigned)
• Confusing predefined role names with custom roles of similar names
• Multiple users with similar names — check correct user

Predefined Role Issues

Predefined Roles Missing

Symptom: Company doesn't have Member, Manager, Admin roles.

Cause: Predefined roles weren't initialized when company was created.

Solution (Platform Admin):

1. Go to Company Roles
2. Click Init Predefined Roles
3. Select the company
4. Click Create Roles

"Predefined roles already exist"

Symptom: Error when trying to initialize predefined roles.

Cause: Roles were already initialized for this company.

Solution: No action needed — the roles already exist. Refresh the page and you should see them.

Cannot Edit Predefined Role Permissions

Symptom: Permission checkboxes are disabled for Member, Manager, or Admin roles.

This is expected behavior. Predefined role permissions are fixed and cannot be changed.

Workaround: Create a custom role with the permissions you need.

Dashboard Access Issues

User Cannot Log Into Dashboard

Symptom: User credentials work for app but not dashboard.

Diagnosis:

1. Check if user has Access Company Dashboard permission
2. Check user's role

Permission check:

• Member role: No dashboard access
• Manager role: Dashboard access
• Admin role: Dashboard access
• Custom roles: Check if Access Company Dashboard is included

Solution:

• Assign user to Manager, Admin, or a custom role with dashboard access
• Or add Access Company Dashboard to their current role (if custom)

Dashboard Sidebar Missing Items

Symptom: User can access dashboard but some menu items are missing.

Cause: Menu items are hidden if user lacks required permission.

Common missing items and their permissions:

Multi-Company Issues

User Has Different Access in Different Companies

Symptom: User reports different access levels in different companies.

This is expected behavior. Users can have different roles in different companies.

Verification:

1. Check user's role in Company A
2. Check user's role in Company B
3. Roles can be completely different

Roles from One Company Appearing in Another

Symptom: Seeing roles from wrong company.

Cause: Company filter not set correctly.

Solution:

1. Check the company context in the dashboard header
2. Use the company filter on the Roles page
3. Ensure you're viewing the intended company

Performance Issues

Roles Page Loading Slowly

Possible causes:

• Large number of roles
• Network latency
• Database query optimization

Workarounds:

• Use filters to reduce results
• Use search to find specific roles
• Contact support if persistently slow

Permission Check Errors in Console

Symptom: Browser console shows permission errors.

This may be normal. The UI preemptively hides elements you don't have access to. Some console errors are expected when permissions are checked.

When to investigate:

• If feature should work but doesn't
• If errors appear during normal operations
• If errors correlate with visible bugs

Getting Help

If you can't resolve an issue:

1. Document the problem:

   • Exact error message
   • Steps to reproduce
   • User's current role
   • Expected vs actual behavior

2. Check logs:

   • Browser console for client errors
   • Backend logs for server errors

3. Contact support:

   • Provide documentation above
   • Include user ID and company ID if possible
   • Screenshots are helpful