# Troubleshooting

> Reading the logs, and the failures that actually happen on a self-hosted deployment.

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/self-hosted/operate/troubleshooting

---
## Where to look first

```bash
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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**

```bash
docker compose exec orangescrum-app php bin/cake.php change_admin_password
```

## Health checks worth automating

- **Container health**: Alert when any service leaves `healthy`.

- **Disk**: Alert at 80% on the volumes holding attachments and the database.

- **Backup freshness and size**: A missing or suddenly-small archive means a failed dump.

- **Certificate expiry**: 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 ps` output
- Whether it reproduces after a cache clear and restart

- [Contact support](mailto:support@orangescrum.com): support@orangescrum.com