Overview
This guide helps you diagnose and resolve common authentication issues in Mapademics, including login failures, invitation problems, session timeouts, and permission errors. The platform uses NextAuth.js with a custom credentials provider and organization-based access control.Login Issues
Cannot Sign In - Invalid Credentials Error
Symptoms:- Login form shows “Invalid credentials” error
- User enters correct email and password but cannot access account
- Error occurs immediately after clicking Login button
1. Email Case Sensitivity
The system converts all emails to lowercase during authentication, but your account might have been created with mixed case. Solution:- Always enter your email address in lowercase
- If you’re unsure of the exact email format, ask your administrator to check the user list
- Example: Use
john.doe@university.eduinstead ofJohn.Doe@University.EDU
2. Account Not Found in Identity Provider
Your account exists in the main user table but not in the authentication provider. Diagnostic Steps:- Confirm your email address with your administrator
- Check if you received a signup invitation email
- Verify you completed the signup process through an invitation link
- If you never received an invitation, ask an administrator to send a new one
- If the invitation expired, request a regenerated invitation
3. Password Issues
Common password-related problems. Solutions:- Ensure you’re using the password you set during the signup process
- Check for caps lock or special character entry issues
- If you’ve forgotten your password, contact your administrator (password reset is not currently self-service)
Session Expires Immediately After Login
Symptoms:- Successfully log in but immediately redirected back to login page
- Can access the application briefly before being logged out
Organization Assignment Missing
Your user account lacks proper organization assignment. Solution: Contact your administrator to verify:- Your user account is assigned to the correct organization
- The organization relationship is properly configured
- For Mapademics Admin users, ensure
maOrganizationIdis set
Database Connection Issues
Temporary database connectivity problems during session validation. Solution:- Wait a few minutes and try again
- If the issue persists, contact support as this indicates a system-level problem
Invitation Problems
Invitation Link Not Working
Symptoms:- Clicking invitation link redirects to error page
- “Invalid invitation” or “Invitation not found” errors
- Signup form doesn’t appear when clicking link
1. Expired Invitation Token
Invitations expire after 24 hours for security purposes. Diagnostic Steps:- Check when the invitation email was sent
- Verify the invitation link hasn’t been modified
- Ask an administrator to regenerate your invitation from Users > Invitations tab
- Use the new invitation link within 24 hours
2. Invitation Already Used
Each invitation can only be used once. Solution:- If you already created an account, use the regular login page
- If you started but didn’t complete signup, ask for a new invitation
3. Malformed Invitation Link
The invitation link was corrupted during email transmission. Solution:- Try copying and pasting the entire link into your browser address bar
- Request a new invitation if the link appears incomplete
Cannot Complete Signup Process
Symptoms:- Invitation link works but signup form submission fails
- Error messages during account creation
- Passwords don’t match even when they appear identical
1. Password Confirmation Mismatch
The system requires exact password matching for security. Solution:- Carefully type both password entries
- Use the “show password” option if available
- Ensure no extra spaces or hidden characters
2. Email Already in Use
An account with this email address already exists. Solution:- Try logging in with the existing account
- If you’ve forgotten your credentials, contact your administrator
- If this is a different person with the same email, contact your administrator for alternative email options
Organization Selection Issues (Admin Users)
Stuck on Organization Selector Page
Symptoms:- Mapademics Admin users redirected to organization selector after login
- Cannot proceed to main application
- Organization list appears empty or incorrect
1. Missing Organization Assignment
Admin user account lacksmaOrganizationId assignment.
Solution:
Contact a system administrator to:
- Verify your admin account has the correct
MAPADEMICS_ADMINrole - Ensure your
maOrganizationIdfield is properly set - Confirm the target organization exists in the system
2. Organization Selection Not Persisting
User selects organization but system doesn’t remember the choice. Solution:- Clear your browser cache and cookies for the site
- Try using an incognito/private browser window
- If the problem persists, this indicates a session storage issue requiring technical support
Permission and Access Issues
Cannot Access Certain Features
Symptoms:- Login successful but some menu items or pages are missing
- “Access denied” or “Insufficient permissions” errors
- Features mentioned in documentation don’t appear
1. Incorrect User Role
Your account has a role that doesn’t match your intended access level. User Roles:USER: Standard access to organization data and featuresADMIN: Full access to organization management and user administrationMAPADEMICS_ADMIN: System-wide access across multiple organizations
2. Organization Context Issues
You’re logged in but the system cannot determine your organization context. Solution:- Log out completely and log back in
- If you’re a Mapademics Admin, ensure you’ve selected the correct organization
- Contact support if organization data appears incorrect
Data Missing or Appears Empty
Symptoms:- Login successful but no programs, courses, or other data visible
- Dashboard shows empty states despite data existing
- Reports show no results
Organization Isolation Issues
Data is isolated by organization, and your account may be assigned to the wrong organization or an empty organization. Solution:- Verify with your administrator that you’re assigned to the correct organization
- Confirm that the organization has data (programs, courses, etc.)
- Check if there are multiple organizations with similar names
Browser and Technical Issues
Login Page Won’t Load or Appears Broken
Symptoms:- White screen or partial page loading
- JavaScript errors in browser console
- Form submissions don’t work
Clear Browser Data
- Clear cache and cookies for the Mapademics site
- Disable browser extensions temporarily
- Try an incognito/private browser window
Browser Compatibility
- Ensure you’re using a supported modern browser (Chrome, Firefox, Safari, Edge)
- Update your browser to the latest version
- Enable JavaScript if it’s disabled
Network Issues
- Check your internet connection
- Try accessing from a different network if possible
- Contact your IT department if you’re behind a corporate firewall
Email Delivery Issues
Not Receiving Invitation Emails
Symptoms:- Administrator sent invitation but email never arrives
- Long delays in email delivery
1. Check Spam/Junk Folders
Invitation emails may be filtered by your email provider.2. Email Server Issues
Your organization’s email server may be blocking automated emails. Contact your IT department to:- Whitelist emails from your Mapademics instance domain
- Check email server logs for blocked messages
- Verify email delivery settings
3. Incorrect Email Address
The invitation was sent to the wrong email address. Solution:- Verify the correct email address with your administrator
- Ask them to check the invitation was sent to the right address
Getting Additional Help
When to Contact Your Administrator
Contact your organization’s Mapademics administrator for:- User role changes or corrections
- New invitation requests or regenerating expired invitations
- Organization assignment issues
- Data access problems specific to your organization
When to Contact Technical Support
Contact Mapademics technical support for:- System-wide login failures affecting multiple users
- Browser compatibility issues
- Email delivery problems that persist after checking with IT
- Database or session management errors
Information to Include When Seeking Help
When contacting support, include:- Error Message: Exact text of any error messages
- Steps to Reproduce: What you were trying to do when the issue occurred
- Browser and Device: Which browser and operating system you’re using
- Email Address: The email address associated with your account
- Organization: Which organization you’re trying to access
- Screenshots: Visual evidence of the problem (hide sensitive information)
Prevention Tips
Best Practices for Avoiding Authentication Issues
- Use Consistent Email Format: Always use lowercase for email addresses
- Act Quickly on Invitations: Complete signup within 24 hours of receiving invitation
- Keep Browser Updated: Use supported browsers with latest updates
- Bookmark the Correct URL: Save the proper login URL to avoid phishing sites
- Communicate with Administrators: Report access issues promptly to prevent account lockouts
For Administrators
- Monitor Invitation Expiry: Regularly check and regenerate expired invitations
- Verify Organization Assignments: Ensure all users are assigned to correct organizations
- Document User Roles: Maintain clear records of who should have what access level
- Test Invitation Process: Periodically test the complete signup workflow
- Email Delivery Setup: Work with IT to ensure reliable email delivery for invitations