Troubleshooting

🛠️ Troubleshooting

This page helps resolve common issues that may occur while running or deploying SecureAuth.

---

🚀 General Troubleshooting Steps

Before debugging:

• Check server logs
• Verify environment variables
• Confirm dependencies are installed
• Restart services if needed

---

🔌 Application Not Starting

---

Problem

Application fails to start.

Example error:

Application crashed

---

Solution

Install dependencies again:

npm install

Start application:

npm run dev

---

⚠️ Port Already In Use

---

Problem

Example error:

EADDRINUSE

---

Solution

Check port usage:

lsof -i :3000

Kill process:

kill -9 PID

---

🌐 Vite Host Blocked

---

Problem

Example error:

Blocked request. This host is not allowed.

---

Solution

Update vite.config.ts

server: {
  allowedHosts: ['yourdomain.com']
}

Restart application afterward.

---

🔐 Environment Variables Missing

---

Problem

Example error:

Missing required environment variable

---

Solution

Verify .env exists.

Example:

cat .env

Restart server after changes.

---

📲 OTP Not Sending

---

Possible Causes

• Invalid TextSnap credentials
• Internet issues
• API limits reached

---

Solution

Verify credentials:

TEXTSNAP_INSTANCE_ID="YOUR_INSTANCE_ID"

TEXTSNAP_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

---

☁️ Firebase Connection Issues

---

Problem

Database connection failing.

---

Solution

Verify Firebase configuration.

Example:

FIREBASE_DATABASE_URL="YOUR_DATABASE_URL"

FIREBASE_DATABASE_SECRET="YOUR_SECRET"

---

🔒 Session Expired

---

Problem

Example response:

{
  "error": "Session expired"
}

---

Solution

Login again.

---

🔑 Invalid JWT Token

---

Problem

Example response:

{
  "error": "Unauthorized"
}

---

Solution

• Clear cookies
• Re-login
• Verify JWT_SECRET

---

📦 Build Failure

---

Problem

Build process fails.

---

Solution

Clear dependencies:

rm -rf node_modules package-lock.json

Reinstall:

npm install

Build again:

npm run build

---

🐳 Docker Issues

---

Container Crashing

Check logs:

docker logs secureauth-app

---

Port Conflict

Check running services:

docker ps

---

⚡ PM2 Issues

---

PM2 App Not Starting

Check logs:

pm2 logs secureauth

---

Restart PM2 Process

pm2 restart secureauth

---

🌐 Nginx Issues

---

502 Bad Gateway

Backend may not be running.

Test backend:

curl http://127.0.0.1:3000

---

Nginx Config Error

Check config:

sudo nginx -t

---

Restart Nginx

sudo systemctl restart nginx

---

🔒 HTTPS Issues

---

SSL Certificate Failure

Renew certificates:

sudo certbot renew

---

📱 PWA Issues

---

PWA Not Updating

Solution:

• Clear browser cache
• Unregister service workers
• Reload application

---

Install Prompt Not Showing

Ensure:

• HTTPS enabled
• Manifest configured correctly
• Icons accessible

---

🧠 Debugging Commands

Useful commands:

---

Check Running Ports

ss -tulnp

---

Check PM2 Processes

pm2 list

---

Check Docker Containers

docker ps

---

Check Logs

pm2 logs

---

🛡️ Security Recommendations

If issues involve authentication:

• Rotate secrets
• Revoke active sessions
• Check suspicious activity

---

🔍 Recommended Troubleshooting Workflow

Check Logs
    ↓
Verify Environment Variables
    ↓
Test Backend
    ↓
Check Reverse Proxy
    ↓
Restart Services

---

📬 Need More Help?

If issues continue:

• Check logs carefully
• Verify deployment configuration
• Confirm environment variables
• Test services individually

---

✅ Related Pages

Continue with:

• Deployment Guide
• Nginx Configuration
• Docker Setup
• PM2 Setup

---

Secure • Fast • Modern ⚡