Troubleshooting Guide

Common issues and solutions when using the PDaaS Console.

Sign-In Issues

I can't sign in

Symptoms:

• Error message: "Invalid email or password"
• Sign-in button doesn't respond
• Redirected back to sign-in page

Solutions:

1. Verify your credentials

   • Double-check your email address (case-sensitive)
   • Ensure caps lock is off when entering password
   • Try revealing the password to verify you typed it correctly

2. Check MFA code

   • MFA codes expire every 30 seconds
   • Generate a fresh code from your authenticator app
   • Ensure your device time is synced correctly

3. Account lockout

   • After 5 failed attempts, accounts are locked for 15 minutes
   • Wait for the lockout period to expire
   • Contact your organization admin if urgent

4. Browser issues

   • Clear browser cache and cookies
   • Try in an incognito/private window
   • Try a different browser
   • Disable browser extensions that might interfere

I forgot my password

1. Click Forgot Password on the sign-in page
2. Enter your email address
3. Check your email for a reset link (valid for 1 hour)
4. Click the link and set a new password
5. Sign in with your new password

If you don't receive the email:

• Check spam folder
• Verify you entered the correct email
• Wait a few minutes and try again
• Contact your organization admin

I lost my authenticator device

If you have recovery codes:

1. On the MFA verification page, click Use recovery code
2. Enter one of your recovery codes
3. Sign in successfully
4. Go to Settings > Security to set up a new MFA device
5. Save your new recovery codes

If you don't have recovery codes:

1. Contact your organization admin
2. Admin can reset your MFA from Security > MFA Admin Tools
3. You'll receive an email with a reset link
4. Complete MFA setup with your new device

MFA Problems

My MFA codes don't work

Common causes:

1. Time sync issue

   • Authenticator apps use time-based codes
   • Ensure your device time is set to automatic
   • On mobile: Settings > Date & Time > Set Automatically

2. Wrong code source

   • Verify you're using the correct app entry for PDaaS
   • You may have multiple entries if you set up MFA multiple times

3. Old codes

   • TOTP codes change every 30 seconds
   • Generate a fresh code and enter immediately

4. Backup codes confusion

   • Recovery codes are different from TOTP codes
   • Each recovery code can only be used once
   • After 10 uses, you'll need new recovery codes

I can't scan the QR code

During MFA setup:

1. Click Enter code manually
2. Copy the secret key
3. Add it manually to your authenticator app
4. Generate a code and verify

Authenticator app recommendations:

• Google Authenticator (iOS, Android)
• Authy (iOS, Android, Desktop)
• 1Password (with TOTP support)
• Microsoft Authenticator

Session Issues

I keep getting signed out

Possible causes:

1. Session timeout

   • Default timeout: 1 hour of inactivity
   • Absolute timeout: 8 hours
   • Check with your org admin to adjust timeout settings

2. Browser settings

   • Enable cookies (required for authentication)
   • Don't clear cookies during active sessions
   • Check if "Remember me" is enabled

3. Multiple tabs

   • Signing out in one tab signs you out everywhere
   • Use the same browser profile for consistency

Session expired message

Why this happens:

• You were inactive for longer than the session timeout
• Your admin revoked your session
• You signed in from another device/browser

Solution:

• Simply sign in again
• Enable "Remember me" for longer sessions

Performance Issues

Console is slow or unresponsive

Quick fixes:

1. Browser cache

   Chrome: Cmd/Ctrl + Shift + Delete
   Firefox: Cmd/Ctrl + Shift + Delete
   Safari: Cmd + Option + E

   • Clear cache and cookies
   • Restart browser

2. Network issues

   • Check your internet connection
   • Try refreshing the page (Cmd/Ctrl + R)
   • Check if other sites are loading slowly

3. Browser extensions

   • Disable ad blockers temporarily
   • Disable browser extensions one by one to identify conflicts
   • Try in incognito/private mode

4. Large datasets

   • Filter data before loading
   • Use pagination (reduce items per page)
   • Export to CSV for offline analysis

API calls failing

Symptoms:

• Error: "Network request failed"
• Infinite loading spinners
• Empty tables or lists

Solutions:

1. Check backend status

   • Contact your administrator
   • Check status page (if available)

2. Verify permissions

   • You may not have access to the resource
   • Check with your admin about your policies

3. Browser console errors

   • Open Developer Tools (F12)
   • Check Console tab for errors
   • Share error messages with support

Data Not Appearing

Users/Groups/Policies not showing up

Checklist:

1. Filters applied

   • Check if filters are active (clear filters button)
   • Reset search query

2. Account scope

   • Verify you're in the correct account
   • Switch accounts using the account switcher

3. Permissions

   • You may not have permission to view the resource
   • Contact your admin to verify policies

4. Cache issue

   • Force refresh: Cmd/Ctrl + Shift + R
   • Clear browser cache

Audit logs missing

Common reasons:

1. Date range filter

   • Expand the date range
   • Default: Last 7 days

2. Action filter

   • Clear action filters
   • Some actions may not generate logs

3. Real-time delay

   • New events appear within 2-3 seconds
   • Refresh the page if needed

Form Errors

Validation errors not clear

Field-specific errors:

• Hover over red highlighted fields
• Error message appears below the field
• Common errors:
  • Email: "Invalid email format"
  • Password: "Must be at least 12 characters"
  • Name: "Required field"

"Something went wrong" error

This usually means:

• Network request failed
• Backend returned an error
• Invalid data submitted

Steps:

1. Check browser console (F12) for detailed error
2. Verify all required fields are filled
3. Try refreshing the page
4. If persists, contact support with:
   • Screenshot of the error
   • Steps to reproduce
   • Browser and version

Export Issues

CSV export failing

Solutions:

1. Large dataset

   • Filter data before exporting
   • Export in smaller batches
   • Use date range filters

2. Pop-up blocked

   • Allow pop-ups for the console domain
   • Download should appear in browser's download bar

3. File corrupted

   • Try a different browser
   • Check if file size is 0 bytes (indicates failed export)
   • Re-export with fewer records

Browser Compatibility

Console doesn't work on my browser

Supported browsers:

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

If using an older browser:

• Update to the latest version
• Switch to a supported browser

Mobile browsers:

• Full functionality on tablets (iPad, Android tablets)
• Read-only on phones
• Some features may not be available

Dark mode issues

If dark mode doesn't work:

1. Check browser supports dark mode
2. Toggle dark mode in User Menu > Settings
3. Try a different browser
4. Clear cache and reload

Contact Support

If you can't resolve the issue:

Before contacting support, gather:

• Description of the problem
• Steps to reproduce
• Screenshots or screen recordings
• Browser and version (e.g., Chrome 120.0.6099.109)
• Error messages (from browser console if possible)

Contact methods:

• Email: [email protected]
• GitHub Issues: github.com/pdaas/pdaas/issues
• Community Forum: community.pdaas.io

Expected response time:

• Email: 24 hours
• Critical issues: 4 hours
• Community: Best effort

Common Error Messages

Error Message	Cause	Solution
"Session expired"	Inactive for too long	Sign in again
"Invalid email or password"	Wrong credentials	Verify email/password, reset if needed
"MFA verification failed"	Wrong TOTP code	Generate fresh code, check time sync
"Permission denied"	Insufficient permissions	Contact admin to verify policies
"Network request failed"	Connection issue	Check internet, refresh page
"User not found"	User doesn't exist	Verify email address is correct
"Email already exists"	Duplicate user	Use a different email address
"Invalid recovery code"	Code already used or wrong	Try another code or contact admin
"Organization not found"	Wrong subdomain	Verify organization slug
"Account locked"	Too many failed attempts	Wait 15 minutes or contact admin

Known Limitations

1. Mobile Support: Full functionality requires tablet or desktop
2. Offline Mode: Console requires internet connection
3. File Upload: Maximum file size for organization logo: 5MB
4. Concurrent Sessions: Signing out in one place signs you out everywhere
5. Export Limits: Maximum 10,000 records per CSV export

Providing Feedback

Found a bug or have a feature request?

1. Bug Reports: GitHub Issues
2. Feature Requests: Feedback Form
3. Documentation Issues: GitHub Docs

Thank you for helping us improve PDaaS Console!