Troubleshooting

Common failures and how to resolve them.

App container restarts on boot

Run docker logs tprm-mlab-app-1. Most common causes:

• DB not healthy yet — harmless; the app retries until MySQL and ClickHouse are up.
• Invalid SESSION_SECRET — must be at least 32 characters.
• Missing LICENSE_KEY — the app refuses to boot without one.

Database connection errors

• Confirm DB_HOST/CH_HOST match the compose service names (mysql / clickhouse) or your external hosts.
• Check the credentials in .env match what the database containers were initialised with. If you changed a password after first boot, the volume still holds the old one — reset it inside MySQL or recreate the volume.
• Verify the containers are on the same Docker network and the databases report healthy: docker compose ps.

Migrations didn't apply

Schema migrations (V1 → V15) run automatically on startup. If a table looks stale, check docker logs tprm-mlab-app-1 for the migration log line. A failed migration is logged with the failing statement; fix the underlying DB issue (permissions, disk space) and restart the app container to retry.

A save shows an error instead of succeeding

This is by design. All create/update operations now surface the underlying SQL error to the UI rather than silently reporting a false success. The red banner contains the constraint or column that failed — common causes are a duplicate contract reference (must be unique), a malformed LEI (must be 20 characters) or a missing mandatory field. Correct the input and retry.

Healthcheck returns license: locked

The instance hasn't been able to contact mlab.sh for 48+ hours. Check outbound HTTPS to mlab.sh:443 from the app container. Once connectivity restores, the lock clears within one hour automatically. Data is never deleted during a lock.

Port already in use

If 8080 is taken, set a different APP_PORT in .env (e.g. APP_PORT=8090) and run docker compose up -d. The MySQL (3306) and ClickHouse (8123/9000) ports stay on the internal network and aren't published.

EBA export validation fails

Open /eba/ and click Validate. The report lists errors, warnings and infos per template. Resolve errors first — they are usually missing mandatory fields, broken references (a contract pointing at a deleted provider), invalid controlled codes, or LEI/date format problems. The deposit package will build cleanly once the register passes validation.

Forgot admin password

Run the recovery command inside the app container:

docker exec -it tprm-mlab-app-1 \
  /app_mlab_sh/bin/admin-reset --email admin@localhost

A one-time reset token is printed; use it at /auth/reset?token=....

Still stuck?

Email [email protected] with the output of /healthz, your license tier and the relevant docker logs snippet. Licensed plans get priority routing.