Troubleshooting

Common issues developers might encounter and their solutions.

Database Connection Refused

Error: ECONNREFUSED 127.0.0.1:5432

Solution:

1. Ensure Docker is running.
2. Check if the database container is up: docker ps.
3. If running pnpm composer:up fails with "port already in use", stop other Postgres instances running on your machine.

Docker Permissions (Linux)

Error: permission denied while trying to connect to the Docker daemon socket

Solution: Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Turbo Build Caching Issues

Issue: Changes aren't being reflected in the build.

Solution: Force a rebuild by ignoring the cache:

pnpm build --force

OIDC Redirect Issues

Issue: "Invalid redirect_uri" when trying to log in.

Solution: Ensure your frontend URL matches what is whitelisted in the OIDC Provider configuration (apps/api/src/auth/oidc/oidc.config.ts).