Database Troubleshooting

This comprehensive troubleshooting guide helps you diagnose and resolve issues with the database switching system. Whether you’re dealing with connection failures, switching problems, or configuration errors, this guide provides step-by-step solutions.

Quick Diagnostics

Start with these commands to understand your current system state:

🔍 System Status

npm run db:status

Shows current configuration, active provider, and available options.

🔗 Connection Test

npm run db:manage test

Tests connectivity to all configured database providers.

💊 Health Check

npm run db:manage health

Runs comprehensive diagnostics and performance checks.

🚨 Emergency Recovery

npm run db:restore

Restores previous configuration if switching failed.

Common Error Messages

“Database not configured”

This error appears when the system can’t find valid database credentials.

Symptoms:

API endpoints return 503 Service Unavailable errors
Dashboard shows “Database service unavailable”
npm run db:status shows “❌ No database providers configured”

Quick Fix
Manual Fix

Check what’s missing:
Terminal window
```
npm run db:status
```
Run the setup wizard:
Terminal window
```
npm run db:wizard
```
Follow the interactive prompts to configure your database

Check your .env file has required variables:
Terminal window
```
cat .env | grep -E "(TURSO|SUPABASE)"
```

Add missing credentials to .env:

# For Turso
TURSO_DATABASE_URL=libsql://your-db-name.turso.io
TURSO_AUTH_TOKEN=eyJ...

# For Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...

Verify file exists and has content:

ls -la .env
wc -l .env  # Should show more than just comments

“Connection failed” During Operations

Database operations timeout or fail to connect to the server.

Symptoms:

Database operations timeout
“Failed to connect” errors in logs
API endpoints return 500 Internal Server errors

Test connectivity to both providers:
Terminal window
```
npm run db:manage test --verbose
```
Check network connectivity (Supabase):
Terminal window
```
curl -I https://your-project.supabase.co
```
Test from different network if possible

“Provider detection failed”

Auto-detection doesn’t select the expected database provider.

Symptoms:

Wrong database provider is selected automatically
Inconsistent behavior between environments
npm run db:status shows unexpected active provider

Solutions:

Set Explicit Provider (Recommended):

# Set explicit provider in .env
echo "DATABASE_PROVIDER=turso" >> .env
# or
echo "DATABASE_PROVIDER=supabase" >> .env

Clear Auto-Detection Issues:

# Remove auto-detection, use explicit choice
sed -i 's/DATABASE_PROVIDER=auto/DATABASE_PROVIDER=turso/' .env

Understand Priority Logic:
- Priority: Explicit choice → Supabase → Turso → Error
- Multiple providers? Set DATABASE_PROVIDER to override

“Schema validation failed”

Operations succeed but data doesn’t match expectations.

Symptoms:

Missing tables or columns
Type conversion errors
Inconsistent data between providers

Quick Schema Check
Migration Fix

npm run db:schema
# Shows detailed schema comparison between providers

For Turso:
Terminal window
```
npm run db:migrate
```
For Supabase:
- Open Supabase Dashboard
- Check migrations in Database → Migrations
- Apply pending migrations

Manual Schema Verification:

# List tables in current database
npm run db:manage tables

# Compare with expected schema in docs

Database-Specific Issues

Turso (LibSQL) Problems

Invalid URL Format

Problem: TURSO_DATABASE_URL has wrong format

Fix:

# ✅ Correct format:
TURSO_DATABASE_URL=libsql://database-name.turso.io

# ❌ Wrong format:
TURSO_DATABASE_URL=https://database-name.turso.io

Authentication Failed

Problem: Auth token expired or invalid

Fix:

Visit: https://app.turso.tech/[org]/[db]/settings/tokens
Generate new token
Update TURSO_AUTH_TOKEN in .env

Database Not Found

Problem: Database doesn’t exist in Turso

Fix:

Verify database exists in Turso dashboard
Check organization and database name spelling
Ensure you have access permissions

Supabase (PostgreSQL) Problems

Invalid API Key

Problem: Using wrong key type for operations

Fix:

# ❌ Don't use anon key for server operations
SUPABASE_ANON_KEY=eyJ...

# ✅ Use service role for server operations
SUPABASE_SERVICE_ROLE_KEY=eyJ...

RLS Policy Violation

Problem: Row Level Security blocks operations

Fix:

Check RLS policies in Supabase Dashboard
Ensure service role can access required tables
Review policy conditions for your use case

Project Paused

Problem: Free tier project paused due to inactivity

Fix:

Visit Supabase Dashboard
Unpause project in Settings
Consider upgrading plan if needed frequently

Switching Operation Issues

Backup Creation Failed

Switching command fails before making configuration changes.

Symptoms:

Switching stops with “backup creation failed”
.env.backup file is not created
File permission errors

Automatic Fix
Manual Backup

Check filesystem permissions:

ls -la .env
ls -la .env.backup 2>/dev/null || echo "Backup doesn't exist"

Fix permissions if needed:
Terminal window
```
chmod 644 .env
```
Retry switching operation

Create backup manually:
Terminal window
```
cp .env .env.backup
```
Verify backup was created:
Terminal window
```
ls -la .env.backup
```
Proceed with switching operation

Environment Update Failed

Switching appears successful but database doesn’t change.

Diagnosis Steps:

Check if .env file is writable:
Terminal window
```
ls -la .env
```

Verify current provider:

npm run db:status | grep "Active Provider"

Check file contents:
Terminal window
```
cat .env | grep DATABASE_PROVIDER
```

Solutions:

Fix Permissions
Manual Update

# Make .env writable
chmod 644 .env

# Retry switching operation
npm run db:switch:turso  # or supabase

# Update environment manually
echo "DATABASE_PROVIDER=turso" >> .env

# Or edit directly with your preferred editor
nano .env  # or vim, code, etc.

Rollback Required

Switch completed but new database configuration doesn’t work.

Immediate Rollback:
Terminal window
```
npm run db:restore
```
Verify Restoration:
Terminal window
```
npm run db:status
```

Manual Rollback (if automatic fails):

cp .env.backup .env
npm run db:status  # Verify restoration

Diagnose Original Issue:

# Test the problematic configuration
npm run db:manage test
npm run db:manage health --verbose

Development Environment Issues

Module Import Errors

Symptoms:

Import errors for database modules
TypeScript compilation fails
“Cannot find module” errors

Solutions:

Node Modules Reset
Cache Issues

Clear Node modules and package lock:
Terminal window
```
rm -rf node_modules package-lock.json
```
Reinstall dependencies:
Terminal window
```
npm install
```
Check TypeScript configuration:
Terminal window
```
npm run type-check
```

Clear npm cache:
Terminal window
```
npm cache clean --force
```
Clear TypeScript cache:
Terminal window
```
npx tsc --build --clean
```
Restart development server:
Terminal window
```
npm run start
```

Hot Reload Not Working

Database configuration changes don’t take effect without server restart.

Expected Behavior: The system supports real-time provider switching without server restart.

Troubleshooting Steps:

Check Current Provider in real-time:

# This should show changes immediately
npm run db:status

Test API Endpoint for real-time switching:

curl http://localhost:4321/api/supabase-test
# Response should show current active provider

Force Restart if needed:

# Kill existing processes
pkill -f "npm run"

# Start fresh
npm run start

Production vs Development Behavior

Symptoms:

Works locally but fails in production
Different database provider selected in different environments

Environment Variables
Configuration Debugging

Check Production Environment Variables:
- Ensure DATABASE_PROVIDER is set explicitly
- Verify all required credentials are present
- Use same credential format as local
Set Explicit Provider in production:
```
DATABASE_PROVIDER=supabase  # or turso
```
Validate Network Access:
- Test database connectivity from production environment
- Check firewall rules and security groups

Compare Environment Files:

# Local
cat .env | grep -E "(DATABASE|TURSO|SUPABASE)" | sort

# Production (if accessible)
env | grep -E "(DATABASE|TURSO|SUPABASE)" | sort

Test Production Database Access:

# From production environment
npm run db:manage test
npm run db:manage health

API Endpoint Issues

Wrong Provider Information

API endpoints report incorrect or inconsistent provider information.

Diagnosis:

Test API Endpoint:

curl http://localhost:4321/api/supabase-test

Check System Status:
Terminal window
```
npm run db:status
```
Compare Results: API response should match system status

Solutions:

Cache Issues
Code Issues

Clear any cached environment variables
Restart development server completely
Check for multiple .env files in different locations

Verify API endpoints use getDatabase() correctly
Check for hardcoded database client imports
Ensure provider detection logic is working

Silent API Failures

Symptoms:

No errors but operations don’t work
Empty results from database queries
API returns success but no data changes

Test Direct Database Connection:
Terminal window
```
npm run db:manage test
```

Check API Logs in development:

npm run dev
# Look for console errors in terminal

Verify Database Tables:
Terminal window
```
npm run db:manage tables
```
Check Permissions (Supabase):
- Review RLS policies in dashboard
- Verify service role permissions

Performance Issues

Slow Database Operations

Symptoms:

API endpoints timeout frequently
Dashboard takes long time to load
Database queries are slower than expected

Performance Diagnosis
Performance Solutions

Run Health Check with timing:
Terminal window
```
npm run db:manage health --verbose
```
Check Network Latency:
- Test connection speed to database
- Consider geographic distance to database server

Compare Providers:

# Switch and compare performance
npm run db:switch:turso
# Test operations...

npm run db:switch:supabase
# Test same operations...

Memory Issues During Switching

Symptoms:

Switching process crashes
Out of memory errors during database operations

Solutions:

Use Dry-Run Mode first:

node scripts/switch-database.js --to turso --dry-run

Stop Other Processes before switching:

# Stop dev server and other resource-intensive processes
pkill -f "npm run"

Switch Without Other Operations running:

npm run db:switch:turso
# Then restart other processes
npm run start

File System Issues

Permission Denied Errors

Symptoms:

Cannot read or write .env files
Script execution fails with permission errors

Fix File Permissions:

chmod 644 .env .env.backup
chmod +x scripts/*.js

Check Directory Permissions:

ls -la .
# Verify you can read/write in current directory

Fix Ownership Issues (if needed):

# Only if files are owned by different user
sudo chown $USER:$USER .env .env.backup

Git Conflicts with Backup Files

Problem: Git wants to commit .env.backup files, causing merge conflicts.

Ensure Backup Files are Ignored:

echo ".env.backup*" >> .gitignore
echo ".env.*.backup" >> .gitignore

Remove from Git if already tracked:

git rm --cached .env.backup
git rm --cached .env.*.backup

Clean Up Repository:

git add .gitignore
git commit -m "Add .env backup files to .gitignore"

Advanced Debugging

Enable Debug Mode

For detailed troubleshooting information:

Environment Debug
Verbose Diagnostics

# Enable debug logging for all database operations
DEBUG=1 npm run db:manage test
DEBUG=1 npm run db:switch:turso

# Get detailed output for all operations
npm run db:manage status --verbose
npm run db:manage health --verbose

Manual Database Testing

Test database connections directly outside the abstraction layer:

Turso Direct Test
Supabase Direct Test

node -e "
import { createClient } from '@libsql/client';
const client = createClient({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN
});
console.log(await client.execute('SELECT 1 as test'));
"

node -e "
import { createClient } from '@supabase/supabase-js';
const client = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_SERVICE_ROLE_KEY
);
const { data, error } = await client
  .from('messages')
  .select('count');
console.log('Result:', data, 'Error:', error);
"

Environment Variable Debugging

Check for hidden characters or configuration issues:

# Check all database-related environment variables
env | grep -E "(DATABASE|TURSO|SUPABASE)" | sort

# Check for invisible characters or extra spaces
od -c .env | grep -E "(TURSO|SUPABASE|DATABASE)"

# Validate .env file format
npm run db:manage validate-config

Recovery Procedures

Complete System Reset

If all else fails, reset the entire database configuration:

Backup Current State:

cp .env .env.emergency-backup
cp .env.backup .env.backup.emergency 2>/dev/null || true

Run Fresh Setup:

npm run db:wizard
# Follow prompts to reconfigure from scratch

Test New Configuration:
Terminal window
```
npm run db:status
npm run db:manage test
```

Restore if Needed:

# If new setup doesn't work
cp .env.emergency-backup .env

Collecting Diagnostic Information

When reporting issues or asking for help, collect this information:

# Create comprehensive diagnostic report
{
  echo "=== System Information ==="
  echo "Node version: $(node --version)"
  echo "NPM version: $(npm --version)"
  echo "OS: $(uname -a)"
  echo

  echo "=== Database Status ==="
  npm run db:status
  echo

  echo "=== Health Check ==="
  npm run db:manage health
  echo

  echo "=== Environment Variables ==="
  env | grep -E "(DATABASE|TURSO|SUPABASE)" | sed 's/=.*/=***/' | sort
} > debug-report.txt

Prevention Best Practices

Regular Health Checks

Add these to your development routine:

# Weekly health check
npm run db:status
npm run db:manage health

# Before major changes
npm run db:backup
npm run db:schema

Safe Development Workflow

Always Backup before experiments:
Terminal window
```
npm run db:backup
```

Test Changes with dry-run first:

node scripts/switch-database.js --to turso --dry-run

Validate Configuration after changes:
Terminal window
```
npm run db:schema
npm run db:manage test
```

Keep Emergency Backup:

# Maintain a known-good configuration
cp .env .env.known-good

Version Control Safety

# Always check before committing
git status | grep -E "(\.env|backup)" && echo "⚠️  Check .env files"

# Verify .gitignore is protecting secrets
git ls-files | grep -E "\.env" && echo "⚠️  .env files in git!"

This troubleshooting guide covers the most common issues you might encounter with the database switching system. For additional help or to report new issues, refer to the main database switching guide or check the project’s GitHub repository for the latest updates and community support.