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 finds the broken layer before you start guessing: the tooling, the containers or the site itself.

Site not loading​

Doctor checks for the causes that keep the site from loading: a stopped Pygmy service, a stopped container or a web server that doesn't answer. If Doctor reports a stopped container, run ahoy up as it suggests, or docker compose up -d without Ahoy. Both commands start the container and keep your database.

If the site still doesn't load, restart the whole stack with the following commands:

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

After down and up, the stack has a fresh database, so 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, the log from ahoy logs database or, without Ahoy, docker compose logs database usually says why the container stopped.

Both last resorts wipe the local database. ahoy build provisions the site again. After the Docker Compose commands, provision the site 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. On Linux, files it creates in the project can end up owned by root on your machine, such as a freshly installed vendor directory. See Default user.

To take ownership back, run the following command:

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

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