Troubleshooting

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.
Missing LICENSE_KEY - the repository docker-compose.yml refuses to start without it. With your own compose file the app starts but stays paused (status missing_key).

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.

Schema migrations (V1 -> V46) 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 (18 alphanumerics followed by 2 check digits) or a missing mandatory field. Correct the input and retry.

Every page shows "Access Denied" / the platform is paused

The instance has no valid license. Sign in as an administrator: the locked page and /settings/license give the reason.

missing_key or invalid - set the current key from mlab.sh in LICENSE_KEY and restart the app container. A rotated key invalidates the old one.
in_use - every place on the license is taken. The locked page lists the instances holding them. Release one on mlab.sh, click Use this instance, or wait: an instance silent for 3 hours gives its place back. This is common after recreating an instance with new volumes, since it gets a new instance id.
expired - mlab.sh was unreachable for more than 7 days. Check outbound HTTPS to mlab.sh:443 from the app container, then click Check again.

The app logs show every check (License guard: ...). Data is never touched while the platform is paused.

Port already in use

If 8080 is taken, change the published side of the ports mapping in docker-compose.yml (for example "8090:8080") and run docker compose up -d. The container always listens on 8080 internally. 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.

There is no default password. Either ADMIN_INITIAL_PASSWORD was set in .env on the first start, or the logs carry a one-time setup link, valid 72 hours:

docker compose logs app | grep "Admin setup"

Open the link (/auth/reset?k=...) on your instance and choose the password. If it expired, restart the app container: a fresh link is printed on each start until a password is set.

Forgot the admin password

The platform sends no email, so Forgot password cannot deliver a link. For admin@localhost, clear its password and restart: a setup link is printed in the logs.

docker compose exec mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" mlabtprm \
  -e "UPDATE users SET password = \"!\" WHERE email = \"admin@localhost\""'
docker compose restart app
docker compose logs app | grep "Admin setup"

For other accounts there is no way yet to recover a password: the platform has no mail service to deliver a reset link. Members of an organisation using single sign-on are not affected.

"Your organization signs in with single sign-on"

The organisation is in SSO only mode: passwords work for local administrators only. Use Sign in with SSO. If the identity provider is down, sign in with a local administrator and turn SSO only off in Organization > General. See Single sign-on for the messages of the SSO sign-in page.

Document uploads fail

"Document storage is not configured": set the S3_* variables and restart the app. See Documents.
413 or the upload stops at a fixed size: a reverse proxy limits request bodies. Raise nginx's client_max_body_size to S3_MAX_UPLOAD_MB.
"The document could not be stored" with SignatureDoesNotMatch, NoSuchBucket or AccessDenied: the storage refused the request. Check the keys, that the bucket exists, and S3_PATH_STYLE (true for MinIO and Silo). /api/v1/files/status?check=1, as an administrator, tests the whole chain.

Still stuck?

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