Troubleshooting Guide

Common issues and solutions for SelfHostedDB

This guide helps you resolve common problems when installing, deploying, or using SelfHostedDB.

Table of Contents

• Database Connection Issues
• Authentication Problems
• Application Won't Start
• Performance Issues
• Docker Issues
• Error Messages Reference

Database Connection Issues

Issue: "Cannot connect to PostgreSQL"

Symptoms:

• Error: ECONNREFUSED or Connection timeout
• Application fails to start
• Health check fails

Solutions:

1. Verify PostgreSQL is running:

   # Check if PostgreSQL is running
   docker ps | grep postgres
   # or
   pg_isready -h localhost -p 5432

2. Check connection string:

   # Test connection manually
   psql "postgres://user:pass@host:5432/dbname"

3. For Docker containers:

   • Use host.docker.internal (Windows/Mac) instead of localhost
   • Use 172.17.0.1 (Linux) instead of localhost
   • Example: postgres://user:pass@host.docker.internal:5432/dbname

4. Check firewall rules:

   • Ensure port 5432 is open (if remote database)
   • Verify security groups (AWS) or network rules (Azure/GCP)

5. Verify credentials:

   • Check username and password are correct
   • Ensure user has proper permissions

Related: See Installation Guide for connection string format

Issue: "SSL/TLS connection required"

Symptoms:

• Error: SSL connection is required
• Connection fails with cloud databases

Solutions:

1. Add SSL parameter to connection string:

   postgres://user:pass@host:5432/dbname?sslmode=require

2. For different SSL modes:

   • sslmode=require - Require SSL (recommended)
   • sslmode=prefer - Prefer SSL, fallback to non-SSL
   • sslmode=disable - Disable SSL (not recommended for production)

Related: See Security Guide for SSL configuration

Authentication Problems

Issue: "Invalid credentials" or "Unauthorized"

Symptoms:

• Can't login to application
• 401 Unauthorized errors
• Authentication fails

Solutions:

1. Verify environment variables:

   # Check if variables are set
   docker exec selfhosteddb env | grep AUTH

2. Check for typos:

   • Verify AUTH_USER and AUTH_PASS are correct
   • Check for extra spaces or special characters
   • Ensure no quotes in environment variables (unless needed)

3. Test authentication:

   # Test Basic Auth
   curl -u admin:secret http://localhost:3001/api/health

4. Clear browser cache:

   • Clear cookies and cached credentials
   • Try incognito/private browsing mode

5. Check API key (if using):

   • Verify API key is correct
   • Check if API key is active
   • Ensure Bearer token format: Authorization: Bearer <key>

Related: See API Documentation for authentication details

Issue: "API key not found" or "Invalid API key"

Symptoms:

• API requests fail with 401
• Error message about invalid API key

Solutions:

1. Verify API key format:

   • Should be 64 characters (hex string)
   • Use Bearer token: Authorization: Bearer <key>

2. Check API key is active:

   • Verify key exists in database
   • Check is_active flag is true

3. Verify schema association:

   • Ensure API key is associated with correct schema
   • Check schema name matches

Related: See API Documentation for API key setup

Application Won't Start

Issue: Container exits immediately

Symptoms:

• Docker container starts then stops
• docker ps shows no running container

Solutions:

1. Check logs:

   docker logs selfhosteddb
   # or
   docker-compose logs app

2. Verify environment variables:

   # Check required variables are set
   docker run --rm your-image env | grep -E "DATABASE_URL|AUTH_USER|AUTH_PASS"

3. Check port conflicts:

   # Check if port 3001 is already in use
   netstat -an | grep 3001
   # or
   lsof -i :3001

4. Verify database connection:

   • Ensure database is accessible
   • Test connection string manually

5. Check Docker resources:

   • Ensure sufficient memory/CPU
   • Check Docker daemon is running

Issue: "Port already in use"

Symptoms:

• Error: EADDRINUSE: address already in use :::3001
• Container fails to start

Solutions:

1. Find process using port:

   # Linux/Mac
   lsof -i :3001
   # Windows
   netstat -ano | findstr :3001

2. Stop conflicting process:

   # Kill process (replace PID with actual process ID)
   kill -9 <PID>

3. Use different port:

   # Change PORT environment variable
   -e PORT=3002
   # Update docker run command
   -p 3002:3002

Performance Issues

Issue: Slow query execution

Symptoms:

• Queries take >5 seconds
• Timeout errors
• High database CPU usage

Solutions:

1. Add database indexes:

   -- Example: Add index on frequently queried column
   CREATE INDEX idx_users_email ON users(email);

2. Optimize queries:

   • Use EXPLAIN ANALYZE to check query plans
   • Add WHERE clauses to limit results
   • Use pagination (default limit is 50 rows)

3. Check connection pool:

   • Monitor active connections
   • Adjust pool size if needed (default: 20)

4. Review query timeout:

   • Default timeout is 30 seconds
   • Consider increasing for complex queries

Related: See Production Guide for performance tuning

Issue: High memory usage

Symptoms:

• Container OOM (Out of Memory) kills
• Slow response times
• High memory consumption

Solutions:

1. Increase container memory:

   # docker-compose.yml
   services:
     app:
       deploy:
         resources:
           limits:
             memory: 2G

2. Review query pagination:

   • Ensure limits are enforced
   • Reduce page size if needed

3. Check for memory leaks:

   • Monitor memory over time
   • Restart container if memory grows continuously

4. Optimize database queries:

   • Add indexes
   • Review query patterns

Docker Issues

Issue: "Cannot connect to Docker daemon"

Symptoms:

• Error: Cannot connect to the Docker daemon
• Docker commands fail

Solutions:

1. Start Docker service:

   # Linux
   sudo systemctl start docker
   sudo systemctl enable docker
    
   # Windows/Mac: Start Docker Desktop

2. Check Docker is running:

   docker ps

3. Add user to docker group (Linux):

   sudo usermod -aG docker $USER
   # Log out and back in

Issue: "Image not found" or "Pull access denied"

Symptoms:

• Error pulling Docker image
• Image not found locally

Solutions:

1. Build image locally:

   docker build -t selfhosteddb:latest .

2. Pull from registry:

   docker pull your-registry/selfhosteddb:latest

3. Check registry credentials:

   docker login your-registry

Issue: Docker Compose fails

Symptoms:

• docker-compose up fails
• Services don't start

Solutions:

1. Check docker-compose.yml syntax:

   docker-compose config

2. Verify all services are defined:

   • Check service names match
   • Verify image names are correct

3. Check dependencies:

   # Ensure database service starts first
   docker-compose up db
   # Then start app
   docker-compose up app

4. View detailed logs:

   docker-compose logs -f

License Issues

Issue: "License required" or "A valid license or trial is required"

Symptoms:

• Error message: License required
• Application blocks access to features
• 403 Forbidden errors

Solutions:

1. Activate a license:

   • Enter your license key and email address
   • Click "Activate License"
   • Verify activation was successful

2. Start a trial:

   • Enter your email address
   • Click "Start Free Trial"
   • You'll have 14 days of full access

3. Check license status:

   curl http://localhost:3001/api/license/status

4. Verify LICENSE_SERVER_URL:

   • Check LICENSE_SERVER_URL environment variable is set
   • Ensure license server is accessible from your application
   • Test connectivity: curl https://your-license-server.com/api/health

5. Check grace period:

   • Paid licenses: 7-day offline grace period
   • Trials: 3-day offline grace period
   • If grace period expired, reconnect to license server

Related: See Installation Guide for license activation steps

Issue: "License key not found" or "Invalid license key"

Symptoms:

• License activation fails
• Error: License key not found or inactive
• Validation returns valid: false

Solutions:

1. Verify license key:

   • Check you're using the correct license key from purchase email
   • Ensure no extra spaces or characters
   • Copy-paste directly from email

2. Verify email address:

   • Use the exact email address associated with your purchase
   • License keys are tied to purchaser's email (prevents sharing)
   • Check purchase confirmation email for correct email

3. Check license server:

   • Verify LICENSE_SERVER_URL is correct
   • Ensure license server is accessible
   • Check license server logs for errors

4. Test validation:

   curl -X POST http://localhost:3001/api/license/validate \
     -H "Content-Type: application/json" \
     -d '{"licenseKey": "your-key", "email": "your-email"}'

Related: See API Documentation for license endpoints

Issue: "License key does not match email address"

Symptoms:

• Error: License key does not match this email address
• Activation fails even with valid license key

Solutions:

1. Use correct email:

   • License keys are tied to the purchaser's email address
   • Use the exact email address from your purchase
   • Check purchase confirmation email

2. Verify purchase:

   • Ensure you're using the license key from your purchase
   • Different purchases have different email addresses
   • Contact support if email doesn't match

Note: This is by design to prevent license sharing. Same owner can deploy on unlimited machines.

Issue: "Trial expired" or "Trial not found"

Symptoms:

• Trial period has ended
• Application blocks access
• Error: Trial expired

Solutions:

1. Purchase a license:

   • Visit the purchase page
   • Complete purchase
   • Activate your license key
   • Trial automatically converts to license

2. Check trial status:

   curl http://localhost:3001/api/trial/status

3. Start new trial (if eligible):

   • Some users may be eligible for a new trial
   • Check trial eligibility with license server

Related: See Installation Guide for license activation

Issue: "Cannot connect to license server"

Symptoms:

• Error: ECONNREFUSED or connection timeout
• License validation fails
• Application uses grace period

Solutions:

1. Check LICENSE_SERVER_URL:

   # Verify environment variable
   docker exec selfhosteddb env | grep LICENSE_SERVER_URL

2. Test connectivity:

   # Test license server accessibility
   curl https://your-license-server.com/api/health

3. Check network/firewall:

   • Ensure application can reach license server
   • Check firewall rules allow outbound HTTPS
   • Verify DNS resolution for license server

4. Use grace period:

   • Application works offline for grace period (7 days paid, 3 days trial)
   • Reconnect to license server before grace period expires

5. For development:

   • Use local license server: LICENSE_SERVER_URL=http://localhost:3002
   • Ensure local license server is running

Related: See Production Guide for license server configuration

Error Messages Reference

Database Errors

Application Errors

API Errors

License Errors

Getting Help

If you're still experiencing issues:

1. Check logs:

   # Docker logs
   docker logs selfhosteddb
    
   # Application logs
   tail -f /var/log/selfhosteddb/app.log

2. Verify configuration:

   • Review environment variables
   • Check database connection
   • Verify network connectivity

3. Test components individually:

   • Test database connection separately
   • Test API endpoints with curl
   • Verify Docker setup

4. Review documentation:

   • Installation Guide
   • Production Guide
   • API Documentation
   • Security Guide

5. Common solutions:

   • Restart containers: docker-compose restart
   • Rebuild images: docker-compose build --no-cache
   • Check for updates: docker pull your-registry/selfhosteddb:latest

Related Documentation

• Installation Guide - Setup and configuration
• Production Guide - Production deployment
• API Documentation - API usage and errors
• Security Guide - Security configuration

Quick Links:

• Having installation issues? See Installation Guide
• Need production deployment help? See Production Guide
• API errors? Check API Documentation
• Security concerns? Review Security Guide

Last Updated: 2025-01-27