Troubleshooting Guide

Common issues and solutions for SelfHostedDB deployment and operation

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

Table of Contents

• License Issues
• Database Connection Issues
• Container Issues
• Network and Connectivity
• Performance Issues
• Authentication Problems
• Data and Query Issues
• Error Messages Reference

License Issues

License Activation Fails

Symptoms:

• CLI tool returns "License activation failed"
• Error message: "License key not found or inactive"

Diagnostic Steps:

# Check license server connectivity
curl -I https://license.selfhosteddb.com/api/health
 
# Check container logs
docker logs selfhosteddb-app
 
# Verify environment variables
docker exec selfhosteddb-app env | grep LICENSE

Solutions:

1. Invalid License Key:

   # Verify you're using the correct key from your email
   # Copy the entire key, including any dashes or special characters

2. Email Mismatch:

   # Use the exact email from your purchase confirmation
   # Email matching is case-sensitive
   docker exec -it selfhosteddb-app activate-license \
     --key "your-key" \
     --email "exact@email.com"

3. Network Connectivity:

   # Test connection from inside container
   docker exec selfhosteddb-app curl https://license.selfhosteddb.com/api/health
    
   # If fails, check firewall rules
   # Ensure outbound HTTPS (port 443) is allowed

4. Expired Trial/License:

   • Check expiration date in your license portal
   • Purchase a new license or extend existing one
   • Visit: https://license.selfhosteddb.com/dashboard (opens in a new tab)

Related: See License Activation Guide for detailed activation steps

Deployment Limit Reached

Symptoms:

• Error: "Your license allows X deployment instance(s)"
• Unable to activate on new machine

Solutions:

# Option 1: Deactivate unused deployment
# Visit: https://license.selfhosteddb.com/dashboard
# Go to "My Licenses" → "Manage Deployments" → "Deactivate"
 
# Option 2: Check current deployments
curl -X POST https://license.selfhosteddb.com/api/license/status \
  -H "Content-Type: application/json" \
  -d '{"licenseKey": "your-key", "email": "your@email.com"}'
 
# Option 3: Purchase additional licenses
# Visit: https://license.selfhosteddb.com/purchase

License File Missing After Restart

Symptoms:

• Container restarts without license
• Must re-activate every time

Cause: License data directory not mounted as volume

Solution:

# Check if volume is mounted
docker inspect selfhosteddb-app | grep -A 5 Mounts
 
# If not mounted, recreate container with volume:
docker rm -f selfhosteddb-app
 
docker run -d \
  --name selfhosteddb-app \
  -v ./license-data:/app/license-data \
  -e DATABASE_URL="..." \
  selfhosteddb:latest
 
# For docker-compose, ensure volume is defined:
volumes:
  - ./license-data:/app/license-data

Grace Period Warnings

Symptoms:

• "License expired but within grace period"
• Application still works but shows warnings

What It Means:

• License has expired but hasn't reached grace period limit
• Paid licenses: 7-day grace period
• Trial licenses: 3-day grace period

Solutions:

# 1. Check time remaining
docker exec selfhosteddb-app curl http://localhost:3001/api/license/status
 
# 2. Renew license before grace period ends
# Visit: https://license.selfhosteddb.com/dashboard
 
# 3. If license server is temporarily down:
# App will continue to work during grace period
# License will auto-validate when server is back online

Cannot Execute CLI Commands

Symptoms:

• Error: "activate-license: command not found"
• Error: "Permission denied"

Solutions:

1. Use Full Path:

   docker exec -it selfhosteddb-app /app/bin/activate-license.js --help

2. Check Script Permissions:

   # Inside container
   docker exec selfhosteddb-app ls -la /app/bin/activate-license.js
    
   # Should show executable bit: -rwxr-xr-x
   # If not, rebuild image
   docker build -t selfhosteddb:latest .

3. Node Not in PATH:

   # Use node directly
   docker exec selfhosteddb-app node /app/bin/activate-license.js --help

Database Connection Issues

Cannot Connect to Database

Symptoms:

• Error: "ECONNREFUSED 127.0.0.1:5432"
• Error: "Connection timeout"
• Container fails to start

Diagnostic Steps:

# Check if database is accessible
docker exec selfhosteddb-app pg_isready -h YOUR_DB_HOST -p 5432
 
# Test connection with psql
docker exec selfhosteddb-app psql "$DATABASE_URL" -c "SELECT 1"
 
# Check container logs
docker logs selfhosteddb-app 2>&1 | grep -i "database"

Solutions:

1. Wrong Host in Docker:

   # ❌ Don't use localhost or 127.0.0.1 for host database
   DATABASE_URL=postgres://user:pass@localhost:5432/db
    
   # ✅ Use host.docker.internal on Docker Desktop
   DATABASE_URL=postgres://user:pass@host.docker.internal:5432/db
    
   # ✅ Use service name in docker-compose
   DATABASE_URL=postgres://user:pass@db:5432/dbname
    
   # ✅ Use actual IP or hostname for remote database
   DATABASE_URL=postgres://user:pass@192.168.1.100:5432/db

2. Firewall Blocking Connection:

   # For PostgreSQL on host machine:
   # Windows: Allow port 5432 in Windows Firewall
   # Linux: 
   sudo ufw allow 5432/tcp
    
   # For cloud databases (RDS, Cloud SQL):
   # Add container/instance IP to security group/firewall rules

3. PostgreSQL Not Listening on Network:

   # Edit postgresql.conf
   listen_addresses = '*'  # or specific IPs
    
   # Edit pg_hba.conf
   host all all 0.0.0.0/0 md5
    
   # Restart PostgreSQL
   sudo systemctl restart postgresql

4. SSL Required:

   # Add sslmode to connection string
   DATABASE_URL=postgres://user:pass@host:5432/db?sslmode=require
    
   # For self-signed certificates:
   DATABASE_URL=postgres://user:pass@host:5432/db?sslmode=disable

Related: See Installation Guide for connection string format

Database Connection Pool Exhausted

Symptoms:

• Error: "remaining connection slots are reserved"
• Slow query performance
• Timeouts under load

Diagnostic Steps:

# Check active connections
docker exec selfhosteddb-app psql "$DATABASE_URL" -c \
  "SELECT count(*) FROM pg_stat_activity WHERE datname = 'your_db'"
 
# Check max connections
docker exec selfhosteddb-app psql "$DATABASE_URL" -c \
  "SHOW max_connections"

Solutions:

1. Increase PostgreSQL max_connections:

   -- In postgresql.conf
   max_connections = 100  -- increase from default 20
    
   -- Restart PostgreSQL

2. Reduce Application Pool Size:

   // In backend/server.js (if needed)
   const pool = new Pool({
     connectionString: process.env.DATABASE_URL,
     max: 10,  // reduce from default 20
   });

3. Find and Kill Idle Connections:

   -- Find idle connections
   SELECT pid, usename, application_name, state, query_start
   FROM pg_stat_activity
   WHERE state = 'idle' AND query_start < NOW() - INTERVAL '10 minutes';
    
   -- Kill idle connections
   SELECT pg_terminate_backend(pid)
   FROM pg_stat_activity
   WHERE state = 'idle' AND query_start < NOW() - INTERVAL '10 minutes';

Container Issues

Container Keeps Restarting

Symptoms:

• Container restarts every few seconds
• docker ps shows status "Restarting"

Diagnostic Steps:

# Check exit code and logs
docker ps -a | grep selfhosteddb
docker logs selfhosteddb-app --tail 50
 
# Check container inspect
docker inspect selfhosteddb-app | grep -A 10 State

Solutions:

1. Missing Required Environment Variables:

   # Ensure all required vars are set
   docker run -d \
     -e DATABASE_URL="postgres://..." \
     -e AUTH_USER="admin" \
     -e AUTH_PASS="password" \
     selfhosteddb:latest

2. Database Not Ready:

   # Use docker-compose with depends_on and healthcheck
   depends_on:
     db:
       condition: service_healthy

3. Port Already in Use:

   # Check if port 3001 is already used
   # Windows PowerShell:
   netstat -ano | findstr :3001
    
   # Linux/Mac:
   lsof -i :3001
    
   # Use different port:
   docker run -p 3002:3001 ...

4. Out of Memory:

   # Check memory usage
   docker stats selfhosteddb-app
    
   # Increase memory limit
   docker run -m 2g ...  # 2GB limit

Volume Mount Permissions

Symptoms:

• Error: "EACCES: permission denied, open '/app/license-data/license.json'"
• Cannot write license file

Solutions:

# Windows: Ensure Docker has access to the folder
# Docker Desktop → Settings → Resources → File Sharing
# Add the parent directory
 
# Linux: Fix ownership
sudo chown -R 1000:1000 ./license-data
chmod 755 ./license-data
 
# Or run container as specific user
docker run --user 1000:1000 ...

Network and Connectivity

Cannot Access UI

Symptoms:

• Browser shows "Connection refused" or times out
• curl http://localhost:3001 fails

Solutions:

1. Check Container is Running:

   docker ps | grep selfhosteddb
    
   # If not running:
   docker logs selfhosteddb-app
   docker start selfhosteddb-app

2. Port Not Published:

   # Check port mapping
   docker port selfhosteddb-app
    
   # Should show: 3001/tcp -> 0.0.0.0:3001
    
   # If not, recreate with -p flag:
   docker run -p 3001:3001 ...

3. Firewall Blocking:

   # Windows: Allow in Windows Defender Firewall
   netsh advfirewall firewall add rule name="SelfHostedDB" dir=in action=allow protocol=TCP localport=3001
    
   # Linux:
   sudo ufw allow 3001/tcp

4. Accessing from Remote Machine:

   # Bind to all interfaces (default)
   docker run -p 3001:3001 ...  # listens on 0.0.0.0:3001
    
   # Access via: http://server-ip:3001
   # Ensure cloud security groups allow inbound 3001

CORS Errors in Browser

Symptoms:

• Browser console: "CORS policy: No 'Access-Control-Allow-Origin' header"
• API calls fail from different domain

Solutions:

// The backend already has CORS configured
// But if you're accessing from a different domain:
 
// Option 1: Update CORS origin in server.js
app.use(cors({ 
  origin: ['http://localhost:3000', 'https://yourdomain.com'],
  credentials: true 
}));
 
// Option 2: Use reverse proxy (nginx, Apache)
// Proxy all requests to backend, avoiding CORS

Performance Issues

Slow Query Execution

Symptoms:

• Queries take >5 seconds
• UI shows loading spinner for long time

Diagnostic Steps:

# Check slow queries in PostgreSQL
docker exec selfhosteddb-app psql "$DATABASE_URL" -c \
  "SELECT query, calls, total_time, mean_time 
   FROM pg_stat_statements 
   ORDER BY mean_time DESC 
   LIMIT 10"
 
# Enable query logging
docker exec selfhosteddb-app psql "$DATABASE_URL" -c \
  "ALTER SYSTEM SET log_min_duration_statement = 1000"  # log queries >1s

Solutions:

1. Add Indexes:

   -- Find missing indexes
   SELECT schemaname, tablename, attname, n_distinct, correlation
   FROM pg_stats
   WHERE schemaname = 'public'
   ORDER BY correlation;
    
   -- Add indexes to frequently queried columns
   CREATE INDEX idx_users_email ON users(email);
   CREATE INDEX idx_orders_user_id ON orders(user_id);

2. Increase Pagination Limit:

   # Reduce page size if fetching too many rows
   # Default is 50 rows per page

3. Database Maintenance:

   -- Vacuum and analyze
   VACUUM ANALYZE;
    
   -- Reindex
   REINDEX DATABASE your_database;

Related: See Production Guide for performance tuning

High Memory Usage

Symptoms:

• Container uses >2GB RAM
• System becomes slow
• OOM (Out of Memory) kills

Solutions:

# Check memory usage
docker stats selfhosteddb-app
 
# Limit container memory
docker run -m 1g --memory-reservation 512m ...
 
# Check PostgreSQL shared_buffers
docker exec selfhosteddb-app psql "$DATABASE_URL" -c "SHOW shared_buffers"
 
# Reduce connection pool size (in server.js)
max: 10  # instead of 20

Authentication Problems

Login Fails with Correct Credentials

Symptoms:

• "Invalid credentials" error
• 401 Unauthorized

Solutions:

1. Check Credentials:

   # Verify environment variables
   docker exec selfhosteddb-app env | grep AUTH_
    
   # Should show:
   AUTH_USER=your_username
   AUTH_PASS=your_password

2. Special Characters in Password:

   # If password contains special characters, use quotes:
   docker run -e AUTH_PASS='p@ssw0rd!' ...
    
   # Or encode in base64 manually:
   echo -n "username:password" | base64

3. Clear Browser Cache:

   # Clear localStorage
   # Browser DevTools → Application → Local Storage → Clear All

Related: See API Documentation for authentication details

Session Expires Too Quickly

Symptoms:

• Logged out after a few minutes
• Have to login frequently

Cause: Basic Auth credentials stored in localStorage

Solution:

• This is expected behavior with Basic Auth
• Credentials are stored in browser localStorage
• They persist until you log out or clear browser data

API Key Issues

Symptoms:

• Error: "API key not found" or "Invalid API key"
• API requests fail with 401

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

Data and Query Issues

Query Returns No Results

Symptoms:

• SELECT query returns empty array
• Data exists in database but not showing in UI

Solutions:

1. Wrong Schema:

   -- Check which schema contains your tables
   SELECT table_schema, table_name 
   FROM information_schema.tables 
   WHERE table_name = 'your_table';
    
   -- Switch schema in UI (use Schema Selector in sidebar)

2. Case-Sensitive Table Names:

   -- PostgreSQL is case-sensitive with quoted identifiers
   SELECT * FROM "MyTable"  -- correct
   SELECT * FROM MyTable    -- wrong (looks for "mytable")

3. Row-Level Security:

   -- Check if RLS is enabled
   SELECT tablename, rowsecurity 
   FROM pg_tables 
   WHERE schemaname = 'public';
    
   -- Temporarily disable for testing
   ALTER TABLE your_table DISABLE ROW LEVEL SECURITY;

Cannot Edit Table Data

Symptoms:

• Inline editing doesn't work
• Update fails with error

Solutions:

1. No Primary Key:

   -- Check for primary key
   SELECT a.attname
   FROM pg_index i
   JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
   WHERE i.indrelid = 'your_table'::regclass AND i.indisprimary;
    
   -- Add primary key if missing
   ALTER TABLE your_table ADD PRIMARY KEY (id);

2. Insufficient Permissions:

   -- Check user permissions
   SELECT grantee, privilege_type 
   FROM information_schema.role_table_grants 
   WHERE table_name = 'your_table';
    
   -- Grant UPDATE permission
   GRANT UPDATE ON your_table TO your_user;

Error Messages Reference

Database Errors

Application Errors

API Errors

License Errors

Getting More Help

Collecting Diagnostic Information

Before contacting support, gather this information:

# 1. Container logs
docker logs selfhosteddb-app > logs.txt
 
# 2. Container configuration
docker inspect selfhosteddb-app > inspect.json
 
# 3. Environment variables (redact sensitive info!)
docker exec selfhosteddb-app env > env.txt
 
# 4. License status
docker exec selfhosteddb-app curl http://localhost:3001/api/license/status > license-status.json
 
# 5. Database connectivity
docker exec selfhosteddb-app psql "$DATABASE_URL" -c "SELECT version()" > db-version.txt
 
# 6. System info
docker version > docker-version.txt
docker info > docker-info.txt

Support Channels

• Documentation: https://docs.selfhosteddb.com (opens in a new tab)
• Email Support: support@selfhosteddb.com
• Community Forum: https://community.selfhosteddb.com (opens in a new tab)
• GitHub Issues: https://github.com/yourorg/selfhosteddb/issues (opens in a new tab)
• License Portal: https://license.selfhosteddb.com/support (opens in a new tab)

Related Documentation

• License Activation Guide - License activation methods and troubleshooting
• Production Deployment Guide - Platform-specific deployment instructions
• Architecture Overview - Technical documentation
• Installation Guide - Setup and configuration
• Production Guide - Production deployment
• API Documentation - API usage and errors
• Security Guide - Security configuration

Quick Links:

• Having license issues? See License Activation Guide
• Need deployment help? See Production Deployment Guide
• Installation problems? See Installation Guide
• Production deployment? See Production Guide
• API errors? Check API Documentation
• Security concerns? Review Security Guide

Last Updated: 2025-12-16