# Troubleshooting

> Reading the logs, and the failures that actually come up on a self-hosted install.

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

Source: https://helpdesk.orangescrum.com/guide/community/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 running?
docker compose ps

# Database reachable?
docker compose exec orangescrum-postgres pg_isready -U orangescrum
```

For a manual install, `logs/error.log` sits in the project root, alongside your
web server's own error log.

## Common failures

**500 on every page after a config change**

    Nearly always a stale cache:

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

    If it persists, `logs/error.log` will name the missing class or template.

**Login succeeds then immediately bounces back**

    A session cookie problem. Check that `FULL_BASE_URL` matches the address you
    are actually using, that `SESSION_COOKIE_DOMAIN` matches the host, and that
    `SESSION_COOKIE_SECURE` is `false` if you are on plain HTTP — a secure
    cookie over HTTP is never stored, so the session is lost on every request.

**Invitations and password resets never arrive**

    SMTP is not configured, or is failing silently. Check `logs/error.log` right
    after triggering a reset. Also check spam — mail sent directly from a VPS
    without SPF and DKIM is usually filtered. See
    [Configuration](https://helpdesk.orangescrum.com/guide/community/install/configuration).

**Attachments upload but won't download**

    The files volume is not mounted where the app expects, or permissions are
    wrong. Confirm the volume exists and that the web server user can read it:

```bash
docker volume ls | grep app-files
docker compose exec orangescrum-app ls -la webroot/files
```

    After a partial restore, the database may reference files that were never
    restored — a database-only restore looks healthy until someone clicks a
    file.

**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 the size; the smallest
    wins.

**The install wizard keeps reappearing**

    The app writes its installed state into `config/`. If that directory is not
    writable, or the Docker config volume was recreated, it cannot tell it has
    been installed.

**Database connection refused**

    From inside the app container the host is the **service name**
    (`orangescrum-postgres`), not `localhost`. Also confirm Postgres is healthy —
    the app has a `depends_on` healthcheck, so a restarting app container often
    means the database never came up.

**Locked out — no working admin**

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

**Disk full**

    Attachments and PostgreSQL data are the two that grow. Check both:

```bash
docker system df -v
```

    Old images and stopped containers are worth pruning, but never with `-v`
    unless you are certain which volumes go with it.

## Health checks worth automating

- **HTTP**: The app container already has a healthcheck. Alert on it going unhealthy.

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

- **Backup freshness**: Alert if last night's dump is missing or suspiciously small.

- **Error rate**: Watch `logs/error.log` for new entries rather than reading it after a complaint.

## Reporting a bug

The Community Edition is version 0.1.0 — bugs are expected. A useful report has:

- What you did, what happened, what you expected
- The relevant lines from `logs/error.log`
- Your version (`VERSION.txt`), PHP version and whether you use Docker
- Whether it reproduces on a fresh install

Open it on
[GitHub](https://github.com/Orangescrum/orangescrum/issues), and see
[Contributing](https://helpdesk.orangescrum.com/guide/community/project/contributing) if you want to fix it
yourself.