Skip to main content

Troubleshooting Common Issues

Installation & Setup​

Docker Compose: containers restart in a loop​

Symptom: docker compose ps shows containers restarting continuously.

Diagnosis:

docker compose logs api --tail=50
docker compose logs db --tail=50

Common causes:

  • DATABASE_URL is wrong — verify the host, port, username, password, and database name.
  • Database is not yet ready when the API starts — add a depends_on with condition: service_healthy for the db service.
  • JWT_SECRET is too short — must be at least 32 characters.

"Cannot connect to database"​

Check:

  1. Is the db container running? docker compose ps db
  2. Is the database password correct? docker compose exec db psql -U $POSTGRES_USER -d $POSTGRES_DB
  3. Is DATABASE_URL in the correct format? postgresql://user:pass@host:5432/dbname

Keycloak shows "Invalid redirect URI"​

Solution: In the Keycloak admin console → Clients → openclm-app → Settings, add your full domain to Valid redirect URIs: https://yourdomain.com/*

Authentication​

Users can't log in — "Realm not found"​

Solution: The Keycloak realm name in .env (KEYCLOAK_REALM) does not match the realm created in Keycloak. Check both match exactly (case-sensitive).

JWT expired errors in the browser console​

Solution: Increase the Access token lifespan in Keycloak admin → Realm Settings → Tokens → Access Token Lifespan. Default is 5 minutes — set to 15–30 minutes for a better UX.

"403 Forbidden" when trying to create a contract​

Cause: Your user does not have the contracts:create permission. Only users with the Contract Author, Contract Manager, Administrator, or Super Admin role can create contracts.

Solution: An administrator must assign you the appropriate role in Settings → Users → [Your Name] → Roles.

Email / Notifications​

No emails are being sent​

Check:

  1. Is SMTP configured? Check SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS in .env.
  2. Test SMTP connectivity from the server: 
    docker compose exec api node -e "
    const nodemailer = require('nodemailer');
    const t = nodemailer.createTransport({host:'$SMTP_HOST', port:587, auth:{user:'$SMTP_USER',pass:'$SMTP_PASS'}});
    t.verify().then(()=>console.log('SMTP OK')).catch(console.error);
    "
  3. Check spam / junk folders.
  4. Verify the SMTP_FROM_EMAIL is not on an email provider's blocklist.

Performance​

The app is slow​

Common causes and fixes:

SymptomLikely causeFix
Slow contract listMissing DB indexRun VACUUM ANALYZE on PostgreSQL
High API response timesToo many concurrent usersAdd PgBouncer connection pooling
UI feels sluggishBrowser memoryRefresh the page; clear browser cache
Slow file uploadsSmall MAX_FILE_SIZE_MB + disk I/OMove uploads to S3-compatible storage

E-Signatures​

Signature request sent but signatory never received it​

  1. Check the signatory's spam folder.
  2. Verify OpenSign's SMTP is configured correctly in the OpenSign admin.
  3. Check OpenCLM's integration settings — confirm the OpenSign API URL is correct and reachable from your server.
  4. In OpenSign's admin, check the signing session status.

Signed PDF not returned to OpenCLM​

OpenSign uses a webhook to return the signed document. If it's not arriving:

  1. Verify the webhook URL is set in OpenSign: https://your-openclm-url/api/webhooks/opensign
  2. Ensure this URL is publicly reachable from the OpenSign server.
  3. Check firewall rules — the OpenSign server must be able to POST to your OpenCLM API port.

Getting More Help​

If you can't resolve your issue here: