Troubleshooting

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

Site not loading

Ahoy

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

Docker Compose

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

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 .