Troubleshooting

When the local environment misbehaves, run Doctor first - it pinpoints the layer that is broken (tooling, containers, or the site itself) before you start guessing.

Site not loading

Ahoy

ahoy doctor                # Check for common issues
ahoy down && ahoy up       # Restart containers
ahoy info                  # Verify URLs and ports

Docker Compose

./vendor/bin/vortex-doctor                       # Check for common issues
docker compose down && docker compose up -d      # Restart containers
docker compose exec cli ./vendor/bin/vortex-info # Verify URLs and ports

Database connection errors

Ahoy

docker compose ps      # Check if the database container is running
ahoy reset             # Last resort: rebuild everything

Docker Compose

docker compose ps      # Check if the database container is running
docker compose down --volumes && docker compose up -d  # Last resort

Permission issues

# Fix file permissions (Linux/Mac)
sudo chown -R $USER:$USER .