Skip to main content
Version: v1

Troubleshooting

This page is for developers whose local stack misbehaves. It covers these symptoms:

  • A site that doesn't load
  • Database connection errors
  • Files in the project that end up owned by root

For failures in CI or on a hosting environment, see Continuous integration and Hosting instead.

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​

Doctor checks the usual causes: a stopped Pygmy service, a stopped container, and a web server that doesn't answer. If it reports a stopped container, run ahoy up as it suggests, or docker compose up -d without Ahoy. Either command starts the container and keeps your database.

If the site still doesn't load, work through the following commands, which restart the whole stack:

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

After either down command, the stack comes back with a fresh database, which is why ahoy down asks you to confirm first. The database lives on an anonymous volume, which plain docker compose down leaves on disk but the next up doesn't mount again. Provision the site again with ahoy provision, or without Ahoy, with docker compose exec cli ./vendor/bin/vortex-provision.

Confirm that the site is back: ahoy doctor ends with [ OK ] All required checks have passed., and the URL that ahoy info prints loads the site.

Database connection errors​

Drupal can't connect to the database when the database container has stopped or keeps restarting. Check the container first, and rebuild only as a last resort:

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

If docker compose ps shows the database container stopped or restarting, ahoy logs database, or docker compose logs database without Ahoy, usually says why. Both last resorts wipe the local database. ahoy build provisions the site again on its own; after the Docker Compose commands, provision it yourself with docker compose exec cli ./vendor/bin/vortex-provision.

Confirm that docker compose ps shows the database container with a status that starts with Up.

Permission issues​

The cli container runs as root, so on Linux, files it creates in the project, such as a freshly installed vendor directory, can end up owned by root on your machine (see Default user). Take ownership back with:

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

Confirm that ls -ld vendor lists your user as the owner.