Troubleshooting

Troubleshooting

Common errors and how to resolve them.

App errors on a missing table

npm run dev only warns about pending migrations, it does not apply them. After pulling changes that add a migration:

npm run db:migrate   # prisma migrate deploy

If you edited prisma/schema.prisma yourself, create the migration:

npx prisma migrate dev --name <change>

"DIRECTORY_ENCRYPTION_KEY absente ou trop courte"

The encryption key is missing or shorter than 32 characters. Set DIRECTORY_ENCRYPTION_KEY to a random string of 32+ characters in .env.local. See Configuration.

Changing this key after secrets are stored makes existing encrypted configs, API keys, and webhook URLs undecryptable. Recreate those connections if you rotate it.

Scan returns 503 "No breach API key configured"

No breach-provider key is stored for the company. Add one on the Data API page (ADMIN only), then retry. See Breach Scanning.

Scan returns 429 or 409

• 429: more than 5 scans for the company in a minute. Wait and retry.
• 409: a scan is already running for the company. Wait for it to finish.

Email alerts never arrive

Email is all-or-nothing. Both RESEND_API_KEY and EMAIL_FROM must be set, otherwise notifications are skipped silently. Recipients are company admins only.

Directory sync fails / connection shows ERROR

The connection stores the failure in errorMessage and sets status = ERROR. Use Test on the connection to re-validate credentials. For SCIM connections, a manual sync is rejected by design: provisioning is pushed by your IdP. See Directory Integrations and SCIM Provisioning.

SCIM requests return 401

The bearer token did not match, the connection id is unknown, or the stored config is unreadable. Confirm the IdP is sending Authorization: Bearer <token> with the exact token issued for that connection. See SCIM Provisioning.

Database connection refused

Ensure the Postgres container is up (npm run db:up) and DATABASE_URL matches it. The compose.yml defaults are postgresql://user:password@localhost:5432/datashield.

CI fails on non-ASCII characters

The compliance workflow blocks non-ASCII in added lines. Replace em dashes, accented characters, and other non-ASCII with ASCII equivalents. See Development.