Troubleshooting User Management
Common issues and solutions for user management
Troubleshooting User Management
This guide covers common issues when managing users in Rahal.
Quick Diagnosis
| Problem | Most Likely Cause | Quick Fix |
|---|---|---|
| User can't login | User inactive | Activate from Users page |
| "No company found" | Domain not verified | Add domain to company |
| "Account pending" | Auto-signup disabled | Activate user manually |
| Can't change email | By design | Create new user instead |
| Role not in dropdown | Role inactive | Activate the role |
| User has wrong access | Wrong role assigned | Change role assignment |
Login Issues
User Can't Login
Symptom: Login fails with credentials error.
Diagnostic Steps:
Solutions by Cause:
| Cause | Solution |
|---|---|
| User inactive | Activate from Users page |
| Company inactive | Activate company |
| Wrong password | Reset password |
| User deleted | Contact platform admin |
| Account locked | Wait or contact admin |
"Account pending approval"
Symptom: User registered but sees pending message.
Cause: Company has auto-signup disabled.
Solution:
- Go to Users
- Find the inactive user
- Change status to Active
- User can now login
OAuth Login Fails
Symptom: Google/Microsoft login doesn't work.
Causes and Solutions:
| Cause | Solution |
|---|---|
| Domain not verified | Add domain to company |
| Company inactive | Activate company |
| Auto-signup disabled | Activate user after first attempt |
Registration Issues
"No company found for this domain"
Symptom: User can't register with company email.
Causes and Solutions:
| Cause | Solution |
|---|---|
| Domain not in verified list | Add domain to company settings |
| Typo in domain | Check spelling in verified domains |
| Company inactive | Activate the company |
| Subdomain used | Add subdomain explicitly |
Email Already Exists
Symptom: Can't create user, email in use.
Solutions:
- Search for existing user with that email
- If found, update existing user instead
- If user should be in different company, contact platform admin
Registration Succeeds But Can't Access
Symptom: User registered, verified email, but can't use app.
Causes:
- Auto-signup disabled (user is inactive)
- Email verification not completed
- Company became inactive
User Creation Issues
Can't Create User
Symptom: Create User button missing or disabled.
Causes and Solutions:
| Cause | Solution |
|---|---|
| Missing permission | You need WRITE_USERS permission |
| No company access | You need access to a company |
| Role inactive | Activate at least one role |
Required Fields Missing
Symptom: Form shows validation errors.
Required Fields:
- Full Name (on create)
- Password (on create)
- Company
- Role
Invalid Email Format
Symptom: Email validation fails.
Solution: Use valid email format: user@domain.com
User Edit Issues
Can't Edit User
Symptom: Edit button missing or form disabled.
Causes and Solutions:
| Cause | Solution |
|---|---|
| Missing permission | You need WRITE_USERS permission |
| User deleted | User cannot be edited after deletion |
| Wrong company | You must have access to user's company |
Email Can't Be Changed
Symptom: Email field is disabled in edit mode.
Cause: This is by design. Email is the user's identity and cannot be changed after creation.
Solution: If email must change, create a new user account.
Company Can't Be Changed
Symptom: Company field is disabled in edit mode.
Cause: This is by design. Company membership is established at creation.
Solution: If user needs to be in a different company, create them in that company separately.
User Status Issues
User Stuck as Inactive
Symptom: User remains inactive despite activation attempt.
Diagnostic Steps:
- Verify save completed successfully
- Refresh the Users list
- Check for error messages
- Verify you have WRITE_USERS permission
Deactivation Not Working
Symptom: User can still login after deactivation.
Causes:
- User has existing session (clears on next request)
- Save didn't complete
Solution: Deactivation takes effect on user's next request, not immediately for existing sessions.
Accidentally Deleted User
Symptom: Need to restore a deleted user.
Solution:
- Deletion is soft-delete (data preserved)
- Contact platform administrator
- Provide user email and details
- Admin can restore from database
Role Assignment Issues
Role Not Appearing
Symptom: Expected role not in dropdown.
Causes and Solutions:
| Cause | Solution |
|---|---|
| Role inactive | Activate the role |
| Role deleted | Create new role or restore |
| Wrong company | Role must belong to user's company |
| Company not selected | Select company first |
Role Change Not Taking Effect
Symptom: User still has old permissions.
Solutions:
- Verify save was successful
- Have user refresh browser
- Have user log out and back in
- Verify role has expected permissions
Permission Issues
User Has Wrong Permissions
Symptom: User can access things they shouldn't or can't access things they should.
Diagnostic Steps:
- Check user's assigned role
- View role's permission list
- Compare with expected permissions
- Remember: base permissions are always included
Missing Dashboard Access
Symptom: User gets error accessing dashboard.
Cause: Role doesn't have ACCESS_COMPANY_DASHBOARD.
Solution: Assign Manager, Admin, or custom role with dashboard access.
Performance Issues
User List Loading Slowly
Symptom: Users page takes long to load.
Solutions:
- Use filters to narrow results
- Reduce page size
- Clear browser cache
Search Not Finding User
Symptom: User exists but search doesn't find them.
Solutions:
- Search matches name and email only
- Try different search terms
- Clear filters (including company filter)
- Check if user is deleted (won't appear)
Best Practices
Preventing User Issues
-
Clear onboarding process
- Document how users should register
- Communicate auto-signup status
- Provide self-service password reset
-
Proactive management
- Regularly review inactive users
- Promptly deactivate departing employees
- Audit role assignments
-
Communication
- Notify users of role changes
- Explain permission changes
- Provide access troubleshooting guide