For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at /guide/self-hosted/operate/troubleshooting.md.
Troubleshooting
Reading the logs, and the failures that actually happen on a self-hosted deployment.
#Where to look first
# Application errors — start here
docker compose exec orangescrum-app tail -100 logs/error.log
# Container output
docker compose logs -f orangescrum-app
# Is everything up and healthy?
docker compose ps
# Database reachable?
docker compose exec orangescrum-postgresdb pg_isready -U orangescrum
On a traditional install, logs/error.log sits in the project root alongside the
web server's own error log.
#Common failures
A container keeps restarting
docker compose logs <service>. The most common cause is a wrong or
missing password in a secrets file — especially after a migration where the
secrets directory was restored incompletely. Confirm every .txt file exists
in ./secrets/.
Database connection refused
The app started before the database was healthy. Check
docker compose ps — the app has a dependency on the database's health
check. From inside a container the host is the service name, not
localhost.
500 on every page after a config change
Stale cache:
docker compose exec orangescrum-app php bin/cake.php cache clear_all
If it persists, logs/error.log names the missing class or template.
Login succeeds then bounces straight back
A session cookie problem. Confirm the configured base URL matches the address people actually use, that the cookie domain matches the host, and that secure cookies are not required while you are serving plain HTTP behind a misconfigured proxy.
Invitations and password resets never arrive
SMTP is not configured or is failing silently. Trigger a reset and check
logs/error.log immediately. Also check spam — mail from a VPS without SPF
and DKIM is usually filtered. SMTP is set during installation and changed in
a server config file, not the admin UI.
Attachments upload but will not download
The files volume is not mounted where the app expects, or permissions are wrong:
docker volume ls | grep app-files
docker compose exec orangescrum-app ls -la webroot/files
After a partial restore the database can reference files that were never restored — the instance looks healthy until someone clicks one.
Uploads fail above a certain size
Raise upload_max_filesize and post_max_size in PHP, and
client_max_body_size in Nginx. All three must allow it; the smallest wins.
Reports / Advanced Dashboard is missing or empty
OS Report only appears when Superset is installed and connected to your
Orangescrum data. In the container stack it is orangescrum-reports, which
waits for orangescrum-reports-db to be healthy — give it ~60 seconds, then:
docker compose logs orangescrum-reports --tail=50
On a traditional install an administrator has to deploy Superset separately.
Daily Catch-Up or reminders never send
The record is written to the database, but delivery runs from a scheduled job on the host. Confirm the cron entries exist — they live outside Docker and are the thing most often lost in a migration.
The installer reappears after a successful install
Installed state is written into config/. Check that directory is writable
and that the app-config volume still exists.
Port not accessible
Firewall or proxy. ufw allow 443/tcp; confirm the reverse proxy forwards to
8080. Do not open 8080 publicly — that bypasses TLS.
Disk full
Attachments and PostgreSQL data are the two that grow:
docker system df -v
df -h
Prune old images and stopped containers — but never with -v unless you are
certain which volumes go with it.
Locked out — no working admin
docker compose exec orangescrum-app php bin/cake.php change_admin_password
#Health checks worth automating
Alert when any service leaves healthy.
Alert at 80% on the volumes holding attachments and the database.
A missing or suddenly-small archive means a failed dump.
An expired certificate is a total outage.
#Escalating to support
Include:
- What you did, what happened, what you expected
- Relevant lines from
logs/error.log - Your Orangescrum version and deployment model (Docker or traditional)
docker compose psoutput- Whether it reproduces after a cache clear and restart