Troubleshooting

Database Connection Failed

# Check database is running
docker compose ps db

# Test connection
docker compose exec db psql -U postgres -c "SELECT 1"

Verify DATABASE_URL format: postgresql://user:pass@host:5432/database

Ollama Models Not Showing

Inside Docker, localhost = the container, not your host machine.

# For host-machine Ollama, use:
OLLAMA_URL=http://host.docker.internal:11434  # macOS/Windows
OLLAMA_URL=http://192.168.1.x:11434           # Linux (use actual IP)

WebSocket/Realtime Not Working

Check NEXT_PUBLIC_SOCKET_URL matches your domain
Verify realtime service is running: docker compose ps realtime
Ensure reverse proxy passes WebSocket upgrades (see Docker guide)

502 Bad Gateway

# Check app is running
docker compose ps steelengine
docker compose logs steelengine

# Common causes: out of memory, database not ready

Migration Errors

# View migration logs
docker compose logs migrations

# Run manually
docker compose exec steelengine bun run db:migrate

pgvector Not Found

Use the correct PostgreSQL image:

image: pgvector/pgvector:pg17  # NOT postgres:17

Certificate Errors (CERT_HAS_EXPIRED)

If you see SSL certificate errors when calling external APIs:

# Update CA certificates in container
docker compose exec steelengine apt-get update && apt-get install -y ca-certificates

# Or set in environment (not recommended for production)
NODE_TLS_REJECT_UNAUTHORIZED=0

Check browser console for errors
Verify NEXT_PUBLIC_APP_URL matches your actual domain
Clear browser cookies and local storage
Check that all services are running: docker compose ps

Windows-Specific Issues

Turbopack errors on Windows:

# Use WSL2 for better compatibility
wsl --install

# Or disable Turbopack in package.json
# Change "next dev --turbopack" to "next dev"

Line ending issues:

# Configure git to use LF
git config --global core.autocrlf input

Workflow Cannot Reach an Internal Service

An API block or a function-block fetch fails with cannot point to private IP addresses, resolves to a blocked IP address, or must use https:// protocol when the target is on your own network.

Workflow egress is deny-by-default for private addresses. Add the destination to EGRESS_ALLOWLIST on both the app and the Temporal Worker, then restart both. The format and the limits are in the Workflow Egress Allowlist section of Environment Variables.

If the error is resolves outside the allowlisted CIDR pin, the host now resolves to an address outside the range you pinned. Confirm the DNS change is expected before widening the pin.

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f steelengine