Troubleshooting

Last updated: May 29, 2026

Depending on your setup, you may have to run the xltrail CLI commands as root/via sudo.

Error Messages

If you get this error when you run xltrail install or xltrail update, double-check your xltrail.conf file and make sure you have an entry with password for DOCKER_REGISTRY_PASSWORD. Alternatively, you may want to try the offline installation.

xltrail status

xltrail status provides an overview of all xltrail Docker containers:

Some containers (e.g., provision, dbmigration, frontend) should show Exited (0) x minutes ago which is expected — they are one-shot containers. There is only an issue if the exit code is not 0.
Exited containers sometimes get cleaned up and hence don’t show up anymore. That’s OK - they will show up again after an xltrail restart.
The rest of the containers should show something like Up x minutes.

xltrail logs

xltrail logs provides a live tail of the logs across all important containers. This is an easy way to debug e.g. the Active Directory / LDAP settings—just run xltrail logs while you login. You can exit out again via Ctrl-C.

Specific logs

You can view logs for a specific service using the CLI or Docker Compose directly. For example, if the database migration fails and you’d like to get access to these logs only, run: xltrail logs dbmigration. You can turn this into a live log via xltrail logs dbmigration --follow.

Support package

Run xltrail support in your terminal to create a support package with all the log files that can be sent to us for further investigation, see also xltrail CLI.