Skip to main content

Troubleshooting

Common issues and solutions for BFFless.

Installation Issues​

Docker Not Found​

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Verify
docker --version
docker compose version

Port Already in Use​

# Check what's using the port
sudo lsof -i :80
sudo lsof -i :443
sudo lsof -i :3000

# Stop conflicting services
sudo systemctl stop nginx apache2

Permission Denied​

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, or run
newgrp docker

SSL/HTTPS Issues​

Certificate Not Found​

# Check if certificates exist
ls -la ssl/

# Ensure files are named correctly
# Should have: fullchain.pem and privkey.pem

Certificate Expired​

# Force renewal
certbot renew --force-renewal

# Copy new certificates
cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem ssl/
cp /etc/letsencrypt/live/yourdomain.com/privkey.pem ssl/

# Restart nginx
docker compose restart nginx

DNS Not Propagated​

Wait 5-30 minutes after updating DNS records. Verify with:

dig yourdomain.com +short
nslookup yourdomain.com

Authentication Issues​

401 "try refresh token" Error​

This means cookies aren't being sent. Common causes:

  1. HTTP instead of HTTPS: Set COOKIE_SECURE=false for HTTP testing
  2. Wrong domain: Ensure API_DOMAIN matches your URL exactly
  3. Third-party cookies blocked: Use same domain for frontend and API
# Fix in .env
COOKIE_SECURE=false
API_DOMAIN=http://localhost

# Restart
docker compose restart backend

Can't Login After Setup​

# Check SuperTokens is running
docker compose logs supertokens

# Restart auth service
docker compose restart supertokens backend

Session Lost on Page Refresh​

Check that FRONTEND_URL and API_DOMAIN match your actual domain.

Database Issues​

Connection Refused​

# Check if database is running
docker compose ps postgres

# Check database logs
docker compose logs postgres

# Verify database is ready
docker compose exec postgres pg_isready -U postgres

Migration Failed​

# Run migrations manually
docker compose exec backend pnpm db:migrate

# Check migration status
docker compose exec backend pnpm db:check

Reset Database​

# Warning: This deletes all data!
docker compose down
docker volume rm bffless_postgres_data
docker compose up -d

Container Issues​

Container Won't Start​

# View logs
docker compose logs <service-name>

# Common services: backend, frontend, nginx, postgres, minio

# Rebuild container
docker compose up -d --build <service-name>

Out of Memory (1GB RAM)​

Stop containers before building:

docker compose down
docker compose -f docker-compose.build.yml build
docker compose up -d

Container Keeps Restarting​

# Check logs for errors
docker compose logs --tail=50 <service-name>

# Check health status
docker compose ps

# Inspect container
docker inspect <container-id>

Network Issues​

Can't Connect to Application​

# Check firewall
ufw status

# Ensure ports are open
ufw allow 80/tcp
ufw allow 443/tcp

# Check nginx is running
docker compose logs nginx

API Returns 502 Bad Gateway​

Backend is not responding:

# Check backend status
docker compose logs backend

# Restart backend
docker compose restart backend

CORS Errors​

Verify API_DOMAIN and FRONTEND_URL in .env match your actual URLs.

Storage Issues​

MinIO Not Accessible​

# Check MinIO status
docker compose logs minio

# Verify credentials in .env match
# MINIO_ROOT_USER and MINIO_ACCESS_KEY should match
# MINIO_ROOT_PASSWORD and MINIO_SECRET_KEY should match

Upload Failed​

# Check storage configuration
docker compose exec backend pnpm db:studio

# Check MinIO bucket exists
docker compose exec minio mc ls local/assets

Storage Credentials Invalid​

If you've changed ENCRYPTION_KEY after initial setup:

# Storage credentials are encrypted with ENCRYPTION_KEY
# Changing it breaks existing configurations
# You'll need to reconfigure storage in the setup wizard

Build Issues​

TypeScript Errors​

# Check types
pnpm --filter frontend exec tsc --noEmit
pnpm --filter backend exec tsc --noEmit

Dependencies Not Found​

# Clean install
rm -rf node_modules apps/*/node_modules
pnpm install

Docker Build Failed​

# Clean build
docker compose build --no-cache

# Check disk space
df -h

# Prune old images
docker system prune -a

Reset Everything​

Soft Reset (Keep Data)​

docker compose restart

Reset Database Only​

docker compose exec postgres psql -U postgres -d assethost -c "TRUNCATE users, assets, api_keys CASCADE;"
docker compose restart backend

Full Reset (Delete All Data)​

docker compose down -v
docker compose up -d

Common Error Messages​

ErrorCauseSolution
ECONNREFUSEDService not runningCheck docker compose ps
401 UnauthorizedInvalid credentialsCheck API key or session
403 ForbiddenNo permissionCheck user role and project access
404 Not FoundResource missingVerify path and IDs
413 Payload Too LargeFile too bigIncrease nginx client_max_body_size
502 Bad GatewayBackend downRestart backend container
504 Gateway TimeoutRequest too slowIncrease timeout settings

Getting Help​

If none of these solutions work:

  1. Check container logs: docker compose logs
  2. Search existing issues on GitHub
  3. Open a new issue with:
    • Error message
    • Relevant logs
    • Environment details (OS, Docker version)
    • Steps to reproduce