Troubleshooting

npm install fails with EACCES permission error

Cause: npm doesn't have permission to write to the global directory.

Solution:

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Or use a Node version manager (recommended)
# Install nvm: https://github.com/nvm-sh/nvm
nvm install 20
nvm use 20

npm run build fails with memory error

Cause: Node.js runs out of memory during the build process (common on servers with limited RAM).

Solution:

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm run build

# For permanent fix, add to .bashrc or .profile
export NODE_OPTIONS="--max-old-space-size=4096"

Error: Cannot find module 'xyz'

Cause: Dependencies not installed or corrupted.

Solution:

# Remove node_modules and reinstall
rm -rf node_modules
rm -f package-lock.json
npm install

Port already in use (EADDRINUSE)

Cause: Another process is using port 6008.

Solution:

# Find process using the port
sudo lsof -i :6008

# Kill the process
sudo kill -9 <PID>

# Or change port in .env
PORT=3000

MongoDB connection failed

Cause: MongoDB server is unreachable or credentials are wrong.

Solutions:

1. Check if MongoDB is running: sudo systemctl status mongod
2. Verify the MONGODB_URI in your .env file
3. For MongoDB Atlas, ensure your server IP is whitelisted in Network Access
4. Test connection manually: mongosh "your_connection_string"

Database creation fails with "not authorized"

Cause: The MongoDB user in your connection string doesn't have sufficient privileges.

Solution: Grant the necessary roles to your MongoDB user:

# Connect to MongoDB as admin
mongosh "mongodb://admin:password@host:port/admin"

# Grant required roles
db.grantRolesToUser("your_user", [
  { role: "dbAdminAnyDatabase", db: "admin" },
  { role: "userAdminAnyDatabase", db: "admin" },
  { role: "readWriteAnyDatabase", db: "admin" }
])

Database shows 0 collections / documents

Cause: The application might be connecting to a different database than expected.

Solutions:

1. Verify the database name matches what's in the metadata
2. Check if the company uses prefixed names (e.g., X7Y8Z9_mydb vs mydb)
3. Ensure the MONGODB_URI points to the correct cluster

Storage limit exceeded error

Cause: Company has exceeded their package's storage limit.

Solutions:

1. Upgrade to a higher package with more storage
2. Delete unused databases or collections
3. Remove unnecessary documents or demo data
4. SaaS Admin can manually restore access: POST /company/admin/storage/companies/:id/restore

Cannot login with default credentials

Cause: Default admin user might not be seeded, or password was changed.

Solutions:

1. Check that the database has been seeded with initial data
2. Verify you're using the correct panel (SaaS Admin at /saas, Company Admin at /)
3. Reset password via the "Forgot Password" link (requires email configuration)

JWT token expired / 401 Unauthorized

Cause: Access token has expired (24 hours) or is invalid.

Solutions:

1. Log out and log in again to get a fresh token
2. If using the API directly, use the refresh token endpoint: POST /auth/company/refresh
3. Ensure JWT_SECRET in .env hasn't changed (changing it invalidates all tokens)

Account locked after too many attempts

Cause: Exceeded maximum login attempts (default: 5).

Solutions:

1. Wait for the lockout duration (default: 30 minutes)
2. SaaS Admin can adjust lockout settings in Settings → Security

"Account suspended" or "Subscription expired" error

Cause: Company status is not active or trial.

Solutions:

1. Contact the SaaS Admin to reactivate your account
2. If expired, subscribe to a new package to restore access
3. SaaS Admin: Change company status in Companies → [Company] → Change Status

Payment gateway not showing

Cause: Gateway is disabled or not configured.

Solution: SaaS Admin should enable the gateway in Settings → Payment Gateways and enter valid API credentials.

Payment fails in test mode

Cause: Using live credentials in test mode or vice versa.

Solution:

1. Ensure the gateway mode matches the credentials (test keys for test mode)
2. For Razorpay test: Use test card 4111 1111 1111 1111
3. Check the gateway's dashboard for error logs

Subscription not activated after payment

Cause: Payment verification webhook might have failed.

Solutions:

1. Check backend logs for payment verification errors
2. Verify webhook URL is correctly configured in the gateway dashboard
3. SaaS Admin can manually upgrade: Payments → Manual Upgrade

Test email not sending

Cause: SMTP credentials are incorrect or provider is blocking.

Solutions:

1. Verify SMTP host, port, username, and password
2. For Gmail: Use an App Password (not your regular password)
3. Check if your email provider requires 2FA app passwords
4. Try port 587 with TLS or port 465 with SSL

Emails going to spam

Solutions:

1. Set up SPF, DKIM, and DMARC records for your domain
2. Use a dedicated email service (SendGrid, Mailgun, AWS SES)
3. Avoid spammy subject lines and excessive HTML
4. Use a custom domain email instead of free email services

Password reset email not received

Solutions:

1. Check spam/junk folder
2. Verify email configuration is working (send test email first)
3. Confirm the email address matches a registered account
4. Check backend logs for email sending errors

Slow page loading

Solutions:

1. Ensure you're running the production build (npm run build then npm start)
2. Use Nginx as a reverse proxy for static file caching
3. Check MongoDB connection latency (use a closer region if using Atlas)
4. Monitor server resources: htop or pm2 monit

High memory usage

Solutions:

1. Increase server RAM (recommended: 2GB+)
2. Set Node.js memory limit: NODE_OPTIONS="--max-old-space-size=2048"
3. Use PM2 with cluster mode: pm2 start npm --name "app" -i max -- start
4. Check for memory leaks in backend logs

API requests timing out

Solutions:

1. Check MongoDB connection health
2. Increase Nginx proxy timeout: proxy_read_timeout 300s;
3. Optimize large queries with pagination and indexing
4. Monitor PM2 logs for error patterns: pm2 logs

CORS errors in browser

Cause: Frontend and backend are on different origins.

Solutions:

1. Update COMPANY_ADMIN_URL and SAAS_ADMIN_URL in backend .env
2. Ensure both panels use the same domain (unified deployment)
3. Check Nginx proxy configuration for proper header forwarding

404 errors on page refresh (SPA routing)

Cause: Server doesn't handle client-side routing.

Solution: This is handled automatically by Next.js. If using Nginx, ensure the reverse proxy is configured correctly to forward all routes to the Node.js server.

SSL/HTTPS not working

Solutions:

1. Verify SSL certificate is valid: sudo certbot certificates
2. Ensure Nginx SSL configuration is correct
3. Check that port 443 is open in firewall: sudo ufw allow 443
4. Test SSL: SSL Labs Test

WebSocket connection fails

Cause: Nginx or proxy not configured for WebSocket upgrade.

Solution: Add WebSocket support to Nginx config:

location /socket.io/ {
    proxy_pass http://127.0.0.1:6008;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

PM2 process keeps restarting

Solutions:

1. Check error logs: pm2 logs mongo-my-admin --err --lines 50
2. Verify all environment variables are set correctly
3. Check MongoDB connection string
4. Ensure the build was successful: npm run build
5. Check for port conflicts

Upgrade breaks existing features

Solutions:

1. Compare your .env with the new .env.example for new required variables
2. Run npm install to install new dependencies
3. Rebuild the application: npm run build
4. Clear browser cache and cookies
5. Restart the server: pm2 restart all