Troubleshooting

Start with the logs of the service that fails:

docker compose logs api --tail 100
docker compose ps

The API does not start

Message: Configuration invalide. The log lists every faulty variable, with the reason. Fix each one in the environment, then restart the api service.

The message says COOKIE_SECURE doit être true en production. Set COOKIE_SECURE=true. The session cookie must be sent over HTTPS.

The message says that a development password is used. The database URL contains dfa_app_dev or dfa_migrator_dev. Replace the passwords of the roles dfa_app and dfa_migrator, and update the URLs.

The message names DATABASE_POOL_MIN. A value above DATABASE_POOL_MAX is refused. Lower the minimum or raise the maximum.

Sign-in fails

The password is refused, and the account is locked. Wait until the lock expires. Repeated failures lock the account for a while. The limit is set by SEUIL_VERROUILLAGE_COMPTE.

Sign-in returns 429. Too many attempts from one address, or too many attempts on one account. Wait for the window to end. If all users are blocked at once, TRUST_PROXY_HOPS is probably wrong, and all users share one address.

The page loads, but you stay signed out. Check that WEB_URL_PUBLIQUE and API_URL_PUBLIQUE use HTTPS and match the addresses in your browser. Check COOKIE_DOMAINE, if you set it.

The database is busy

Message: timeout exceeded when trying to connect. All connections of the pool are in use. Look for a slow query in the logs, or raise DATABASE_POOL_MAX if the server has room. Check the PostgreSQL max_connections limit too.

E-mails do not arrive

Messages are sent for real only when NODE_ENV=production, COURRIEL_ENVOI_REEL=true, and the SMTP_* variables are set. Otherwise the messages are captured and not delivered. Check these variables first, then the logs of the api service for the SMTP error.

The vehicle OCR does not read the document

The OCR service must be running and reachable from the API at OCR_SERVICE_URL. If the service is slow, raise OCR_SERVICE_TIMEOUT_MS. An error that says the service is unavailable means the request was not processed, so try again.

The data import stops

The import stops with an error that the Access tools are unavailable. An Access archive needs the mdbtools programs. The API container includes them. If you run the API outside the container, install mdbtools on the server.

The import reports skipped records. Read the reason given for each skipped record in the plan or the report.

The page is blank after an upgrade

Check that the web container is running, and that its version matches the API version. Clear the cache of the browser, then reload. Check the logs of the web service.

The migration failed

The API does not start on the new version, and the previous version keeps running. Read the logs of the migrate service, fix the cause in a new release, and run the upgrade again. Do not edit a migration file that has already been applied.

Where to get more help

Open an issue on the GitHub repository with the version, the relevant log lines, and the steps to reproduce. Remove any personal data and any secret before you paste a log.