Project Issues

Troubleshooting Supabase project problems.

Solutions to common issues when creating and managing Supabase projects.

Project Creation Issues

Creation Stuck at "Pulling Images"

Problem: Project creation hangs during Docker image download.

Solutions:

Check Docker Hub connectivity:

docker pull supabase/postgres:15.6.1.139

Check disk space:

df -h
# Need at least 10GB free for images

Clean up Docker:
```
docker system prune -a
```
Check Docker daemon logs:
```
journalctl -u docker -f
```

"Project directory already exists"

Error:

{
  "success": false,
  "error": "Project directory already exists"
}

Solution:

# Check if directory exists
ls -la ~/supabase/projects/

# Remove orphan directory if project doesn't exist in Supascale
rm -rf ~/supabase/projects/your-project-name

# Retry project creation

Container Health Check Failing

Problem: Containers start but become unhealthy.

Diagnostic Steps:

Check container logs:

cd ~/supabase/projects/your-project
docker compose logs -f

Check specific service:

docker compose logs db
docker compose logs kong
docker compose logs auth

Check container status:
```
docker compose ps
```

Common Causes:

Memory exhaustion: Increase server RAM or reduce services
Port conflicts: Another service using required ports
Database corruption: Reset the project

Project Startup Issues

Project Won't Start

Problem: Start button does nothing or fails immediately.

Solutions:

Check Docker:
```
docker ps
docker compose version
```

Check project directory:

ls -la ~/supabase/projects/your-project/
# Should contain docker-compose.yml

Manual start to see errors:

cd ~/supabase/projects/your-project
docker compose up

Services Starting But Not Accessible

Problem: Containers running but dashboard shows offline.

Check:

Verify containers are healthy:

docker compose ps
# All should show "healthy" status

Check Kong gateway:
```
docker compose logs kong
```
Test direct access:
```
curl http://localhost:54321/rest/v1/
```

"Container not found" Errors

Error: Status checks return container not found.

Solution:

# List all containers
docker ps -a

# If containers are stopped
cd ~/supabase/projects/your-project
docker compose up -d

# If containers are missing, recreate
docker compose down
docker compose up -d

Database Issues

Cannot Connect to Database

Problem: Database service shows unhealthy.

Solutions:

Check PostgreSQL logs:
```
docker compose logs db
```
Check if port is accessible:
```
docker compose exec db pg_isready
```
Check database credentials:
- Verify POSTGRES_PASSWORD in .env
- Try connecting with psql:
```
docker compose exec db psql -U postgres
```

Database Out of Memory

Error:

FATAL: out of shared memory

Solution:

Edit docker-compose.yml to increase PostgreSQL memory:

services:
  db:
    command: >
      postgres -c shared_buffers=256MB
               -c work_mem=16MB

Then restart:

docker compose down
docker compose up -d

Database Disk Full

Error:

PANIC: could not write to file: No space left on device

Solution:

# Check disk usage
df -h

# Clean Docker
docker system prune -a --volumes

# Or expand disk/add storage

Service-Specific Issues

Auth Service Not Working

Symptoms: Login/signup fails, 500 errors.

Solutions:

Check Auth logs:
```
docker compose logs auth
```
Verify JWT secrets:
- Check JWT_SECRET in .env
- Ensure it matches across services
Check SMTP configuration (if email verification enabled):
- Verify SMTP settings in project settings

Storage Service Errors

Symptoms: File uploads fail.

Solutions:

Check Storage logs:
```
docker compose logs storage
```
Verify storage directory permissions:
```
ls -la volumes/storage/
```
Check S3 configuration (if using external storage)

Realtime Not Connecting

Symptoms: Subscriptions don't work.

Solutions:

Check Realtime logs:
```
docker compose logs realtime
```
Verify WebSocket connectivity:
- Check if port 54321 allows WebSocket upgrade
- Check reverse proxy WebSocket configuration

Check database publication:

SELECT * FROM pg_publication;
-- Should show supabase_realtime

Performance Issues

Slow Project Performance

Diagnostic:

# Check container resource usage
docker stats

# Check system resources
htop

Solutions:

Increase container memory limits: Edit docker-compose.yml:

services:
  db:
    deploy:
      resources:
        limits:
          memory: 2G

Disable unused services via Project Settings
Add database indexes for frequently queried columns

High CPU Usage

Common causes:

Unoptimized queries
Too many active connections
Realtime subscriptions with large datasets

Solutions:

Review and optimize slow queries
Enable connection pooling (PgBouncer)
Limit Realtime subscriptions

Project Deletion Issues

Cannot Delete Project

Problem: Delete button fails.

Manual cleanup:

# Stop containers
cd ~/supabase/projects/your-project
docker compose down -v

# Remove directory
rm -rf ~/supabase/projects/your-project

# Remove from Supascale database (if needed)
# Use Supascale API or wait for next sync

Orphan Containers After Deletion

Problem: Docker containers still running after project deletion.

Solution:

# Find orphan containers
docker ps -a | grep your-project

# Stop and remove
docker stop $(docker ps -aq --filter name=your-project)
docker rm $(docker ps -aq --filter name=your-project)

# Clean up volumes
docker volume prune

Getting Help

When reporting project issues, include:

Project logs:

cd ~/supabase/projects/your-project
docker compose logs > project-logs.txt

Container status:
```
docker compose ps
```
System resources:
```
free -m
df -h
docker system df
```