Troubleshooting Guide

Solutions to common issues and errors when running WiLicensor Server.

Table of Contents

• Database Issues
• Email Issues
• Session Issues
• Webhook Issues
• Authentication Issues
• API Issues
• Deployment Issues

Database Issues

Database Connection Fails

Symptoms:

• "Unable to connect to database" error on startup
• Application starts in limited mode
• 503 errors on admin routes

Solutions:

1. Verify PostgreSQL is running:

# Check if PostgreSQL is accepting connections
pg_isready -h your-host -p 5432

Expected output:

your-host:5432 - accepting connections

2. Test credentials:

# Try connecting directly
psql -h your-host -U your-user -d your-database

If connection fails, check:

• Username is correct
• Password is correct
• Database name exists
• Host is reachable

3. Check SSL configuration:

For local development:

POSTGRES_SSL=false

For production (Heroku, Neon, etc.):

POSTGRES_SSL=true

4. Check environment variables:

# Windows (PowerShell)
$env:POSTGRES_HOST
$env:POSTGRES_USER
$env:POSTGRES_DATABASE

# Linux/Mac
echo $POSTGRES_HOST
echo $POSTGRES_USER
echo $POSTGRES_DATABASE

5. Check firewall:

• Ensure PostgreSQL port (5432) is not blocked
• Check cloud provider security groups/firewall rules
• For local development, disable firewall temporarily to test

6. Review logs:

# Application logs
npm run dev  # Look for error messages

# PostgreSQL logs (location varies by OS)
# Windows: C:\Program Files\PostgreSQL\15\data\log\
# Linux: /var/log/postgresql/

Table Does Not Exist

Symptoms:

• "relation does not exist" error
• Queries fail for specific tables

Solutions:

1. Verify table exists:

psql -h your-host -U your-user -d your-database -c "\dt"

2. Restart application (creates tables automatically):

npm run dev

3. Check model definitions in models/ directory

4. Force sync (WARNING: Drops all tables):

// Temporary code in app.js
await sequelize.sync({ force: true });  // DANGER: Drops tables

Session Table Missing

Symptoms:

• Sessions don't persist
• Logged out after browser refresh
• "session_pg table does not exist" error

Solutions:

1. Check if table exists:

psql -h your-host -U your-user -d your-database -c "\dt session_pg"

2. Create table manually:

CREATE TABLE "session_pg" (
  "sid" varchar NOT NULL COLLATE "default",
  "sess" json NOT NULL,
  "expire" timestamp(6) NOT NULL
)
WITH (OIDS=FALSE);

ALTER TABLE "session_pg" ADD CONSTRAINT "session_pkey" PRIMARY KEY ("sid") NOT DEFERRABLE INITIALLY IMMEDIATE;

CREATE INDEX "IDX_session_expire" ON "session_pg" ("expire");

3. Enable auto-creation in sessions.js (should already be enabled):

store: new pgSession({
  pool: sequelize.connectionManager.pool,
  tableName: 'session_pg',
  createTableIfMissing: true  // Ensure this is true
})

Database Outage Handling

Symptoms:

• Database temporarily unavailable
• Admin dashboard returns 503
• API still works with fallback

Expected Behavior:

• /api/check provides 24-hour grace period
• Admin routes return 503 Service Unavailable
• Application recovers automatically when DB reconnects

Verify Fallback:

# Should return fallback response even with invalid key
curl "http://localhost:5000/api/check?term=any_long_string_over_20_chars"

Expected response:

{
  "key": "any_long_string_over_20_chars",
  "condition": "activated",
  "type": "outage_fallback",
  "_outage_fallback": true,
  "_outage_fallback_expires": "2025-12-19T10:00:00.000Z"
}

Email Issues

Email Not Sending

Symptoms:

• No emails received from system
• "Email sending failed" in logs
• SMTP connection errors

Solutions:

1. Test SMTP connection:

node test.js

Expected output:

Email sent: 250 2.0.0 OK ...

2. Verify Gmail App-Specific Password:

Problem: Using regular Gmail password instead of app-specific password

Solution:

1. Enable 2-factor authentication on Gmail
2. Generate App-Specific Password: https://support.google.com/accounts/answer/185833
3. Use the 16-character password in EMAIL_PASSWORD

3. Check environment variables:

# Verify all email variables are set
echo $EMAIL_SENDER        # your-gmail@gmail.com
echo $EMAIL_PASSWORD      # app-specific password (16 chars)
echo $EMAIL_FROM_ALIAS    # Display name
echo $EMAIL_RECIPIENT     # Admin email

4. Verify Gmail settings:

• 2-factor authentication enabled
• App-specific password generated
• IMAP enabled (Settings → Forwarding and POP/IMAP)

5. Check SMTP configuration in mailer.js:

{
  host: 'smtp.gmail.com',
  port: 465,
  secure: true,  // SSL
  auth: {
    user: process.env.EMAIL_SENDER,
    pass: process.env.EMAIL_PASSWORD
  }
}

6. Test with different email:

Temporarily change EMAIL_SENDER to another Gmail account to isolate issue.

Emails Going to Spam

Symptoms:

• Emails sent successfully but land in spam folder

Solutions:

1. Check SPF/DKIM records (if using custom domain):

• Add SPF record for Gmail: v=spf1 include:_spf.google.com ~all
• Enable DKIM in Gmail settings

2. Improve email content:

• Avoid spam trigger words
• Include unsubscribe link (for marketing emails)
• Use professional "From" name

3. Use dedicated email service (for production):

• SendGrid
• Mailgun
• Amazon SES

Session Issues

Sessions Not Persisting

Symptoms:

• Logged out after browser refresh
• "Session expired" immediately after login

Solutions:

1. Verify SESSION_SECRET is set:

echo $SESSION_SECRET

Should be 128+ characters. If not set:

npm run secret
# Copy output to .env.local

2. Check session_pg table exists:

psql -h your-host -U your-user -d your-database -c "SELECT COUNT(*) FROM session_pg;"

3. Verify cookie settings in sessions.js:

cookie: {
  maxAge: 30 * 24 * 60 * 60 * 1000,  // 30 days
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production'  // false for dev
}

4. Check browser cookies:

• Open DevTools → Application → Cookies
• Look for connect.sid cookie
• Verify it's not being blocked

5. For HTTPS sites, ensure secure: true:

cookie: {
  secure: true  // Only for HTTPS
}

"Invalid session secret"

Symptoms:

• Application won't start
• "Session secret is required" error

Solutions:

1. Generate new secret:

npm run secret

2. Add to .env.local:

SESSION_SECRET=your_128_character_hex_string

3. Restart application:

npm run dev

Webhook Issues

Webhooks Not Receiving Events

Symptoms:

• Payment processed but no license keys created
• Webhook shows as failed in payment platform

Solutions:

1. Verify webhook URL in payment platform:

Stripe:

• Go to Webhooks
• Check endpoint: https://yourdomain.com/webhook/stripe
• Verify events: customer.subscription.created, customer.subscription.deleted

2. Check webhook signature:

Ensure STRIPE_WEBHOOK_SECRET matches value in Stripe dashboard.

3. Test locally with ngrok:

# Start ngrok
ngrok http 5000

# Use ngrok URL in Stripe
https://abc123.ngrok.io/webhook/stripe

# Test with Stripe CLI
stripe listen --forward-to localhost:5000/webhook/stripe
stripe trigger customer.subscription.created

4. Check webhook logs:

Stripe Dashboard → Webhooks → Click endpoint → Recent deliveries

Look for:

• Response code (should be 200)
• Error messages
• Request/response bodies

5. Verify webhook payload:

Add temporary logging in routes/webhook.js:

router.post('/webhook/stripe', async (req, res) => {
  console.log('Webhook received:', JSON.stringify(req.body, null, 2));
  // ... rest of code
});

6. Check signature verification:

If signature fails:

• Verify STRIPE_WEBHOOK_SECRET is correct
• Check if using test vs. production secret
• Ensure raw body is available (not parsed JSON)

Keys Not Created from Webhook

Symptoms:

• Webhook received successfully (200 response)
• No license keys created in database

Solutions:

1. Check webhook logs:

# Application logs
npm run dev  # Look for error messages

2. Verify product exists:

If autoAdd setting is disabled, product must exist in database.

Enable autoAdd:

1. Login to admin dashboard
2. Go to Settings
3. Enable "Auto Add Products"
4. Save

3. Check metadata in Stripe:

Webhook expects:

{
  "metadata": {
    "productName": "Your Product Name",
    "quantity": "1"
  }
}

4. Verify email is sent:

Check admin email (EMAIL_RECIPIENT) for notification.

Authentication Issues

Cannot Login

Symptoms:

• "Invalid username or password" error
• Correct credentials don't work

Solutions:

1. Verify email normalization:

Try logging in with:

• Lowercase email: user@example.com
• Not: User@Example.com or USER@EXAMPLE.COM

2. Check user exists:

psql -h your-host -U your-user -d your-database -c "SELECT username, email FROM users;"

3. Reset password (admin access required):

1. Login to admin dashboard
2. Go to Manage Users
3. Edit user
4. Set new password

4. Check password hashing:

Passwords should be bcrypt hashed. If you see plain text passwords in database, model setter isn't working.

"Admin access required"

Symptoms:

• 403 Forbidden error
• Cannot access admin routes

Solutions:

1. Verify user role:

psql -h your-host -U your-user -d your-database -c "SELECT username, role FROM users;"

2. Update user role (if you have database access):

UPDATE users SET role = 'admin' WHERE email = 'your-email@example.com';

3. Create new admin user:

If no admin exists and ensureAdmin logic allows:

1. Visit /register
2. Create new user
3. If no users exist, first user becomes admin

API Issues

API Returns 400 for Valid Key

Symptoms:

• Valid license key returns "Invalid key" error
• Key exists in database

Solutions:

1. Check key format:

Ensure key matches encryption output:

curl "http://localhost:5000/keys/gen?term=YOUR_MACHINE_ID"

2. Verify key condition:

psql -h your-host -U your-user -d your-database -c "SELECT key, condition FROM keys WHERE key = 'YOUR_KEY';"

Key must have condition = 'activated' or 'ok' (not 'expired' or 'deactivated').

3. Check expiration:

psql -h your-host -U your-user -d your-database -c "SELECT key, \"endAt\" FROM keys WHERE key = 'YOUR_KEY';"

If endAt is in the past, key is expired.

API Returns 500 Error

Symptoms:

• Internal server error
• No specific error message

Solutions:

1. Check application logs:

npm run dev  # Look for stack traces

2. Enable verbose logging:

Add to route handler:

router.get('/api/check', async (req, res) => {
  try {
    console.log('Query params:', req.query);
    // ... rest of code
  } catch (error) {
    console.error('Full error:', error);
    // ...
  }
});

3. Check database connection:

500 errors often indicate database issues. Verify connection is active.

Deployment Issues

Vercel: "Module not found"

Symptoms:

• Deployment succeeds but runtime error
• "Cannot find module" error

Solutions:

1. Check package.json:

Ensure all dependencies are in dependencies, not devDependencies:

{
  "dependencies": {
    "express": "^4.17.1",
    "sequelize": "^6.37.1"
  }
}

2. Verify vercel.json configuration:

{
  "version": 2,
  "builds": [
    {
      "src": "app.js",
      "use": "@vercel/node"
    }
  ]
}

3. Check build logs in Vercel dashboard

Heroku: Database Connection Fails

Symptoms:

• Application crashes on Heroku
• Database connection errors

Solutions:

1. Verify DATABASE_URL is set:

heroku config:get DATABASE_URL

2. Check SSL configuration:

Heroku PostgreSQL requires SSL. Ensure in config/database.js:

dialectOptions: {
  ssl: {
    require: true,
    rejectUnauthorized: false
  }
}

3. Check Heroku logs:

heroku logs --tail

Docker: Container Exits Immediately

Symptoms:

• Docker container starts then stops
• No error messages

Solutions:

1. Check container logs:

docker logs container_name

2. Run interactively:

docker run -it --env-file .env.local license-server sh

3. Verify environment variables:

docker run --env-file .env.local license-server printenv

4. Check database connectivity from container:

docker run -it --env-file .env.local license-server sh
# Inside container
apk add postgresql-client
psql -h $POSTGRES_HOST -U $POSTGRES_USER -d $POSTGRES_DATABASE

Getting Help

Before Asking for Help

1. Check application logs (npm run dev)
2. Check database connection (psql or pg_isready)
3. Test email (node test.js)
4. Review environment variables
5. Search this troubleshooting guide

Information to Include

When reporting issues, include:

1. Error message (full stack trace)
2. Environment:
   • OS (Windows, Linux, Mac)
   • Node.js version (node --version)
   • PostgreSQL version (psql --version)
3. Configuration (sanitized):
   • .env.local (remove passwords)
   • Hosting platform (Vercel, Heroku, etc.)
4. Steps to reproduce
5. Expected vs. actual behavior
6. Logs (application and database)

Support Channels

• GitHub Issues (create new issue)
• Project documentation (README.md, CLAUDE.md)
• Email support (if configured)

Related Documentation

• ← Back to README
• Configuration Guide
• API Documentation
• Deployment Guide
• Development Guide
• Technical Details

Last Updated: 2025-12-18