# Troubleshooting Nextcloud

When Nextcloud is not working correctly, the cause is usually one of a few things. Common causes include a hostname not in `trusted_domains`, background jobs not running, Redis or the database being unreachable, upload limits too low, or a half-finished upgrade. This page shows where to look and how to work through a problem methodically. Most fixes use the `occ` command, run as the system user from the `public_html` directory.

## Where to find the logs

| Component | Where |
| --- | --- |
| Nextcloud application log | `data/nextcloud.log` inside the data directory (`/var/www/<user>/.../data/nextcloud.log`); also visible under **Administration settings > Logging** |
| Nginx access/error log | the host's web-server logs under the system user's home, e.g. `/var/www/<user>/logs/` |
| PHP-FPM log | the PHP-FPM pool/error log for the site's runtime |
| Database | the MySQL/MariaDB or PostgreSQL service log |
| config.php | `/var/www/<user>/.../public_html/config/config.php` - inspect with `occ config:list system`, do not hand-edit while online |

Also use the host's [Health](../../platform/hosts/health.md) tab for service status and resource alerts, and review recent deploys in [History](../../platform/hosts/revisions.md).

> [!TIP]
> Raise the log level temporarily with `occ log:manage --level debug`, reproduce the issue, then set it back to `warning` so the log stays readable.

## Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| "Access through untrusted domain" when opening the site | The hostname is not in `trusted_domains` | Add it: `occ config:system:set trusted_domains <n> --value=cloud.example.com`. Behind a proxy/Content Delivery Network (CDN), also set `trusted_proxies` and `overwrite.cli.url`. |
| Admin warns "last background job ran long ago" | Background jobs not running via system cron | Set cron mode: `occ background:job:mode cron` and ensure the system scheduler runs `cron.php` every 5 minutes (`nextcloud_background_cron`). |
| Site shows "maintenance mode" and stays there | Maintenance flag left on after an upgrade/backup | Turn it off: `occ maintenance:mode --off`. If an upgrade was interrupted, run `occ upgrade` then turn it off. |
| File locking errors / "files locked" | Redis unreachable, so transactional locking fails | Confirm Redis is running as a [service](../../platform/hosts/services.md) and reachable on its socket; verify `memcache.locking` in config. As a last resort clear stale locks in the `oc_file_locks` table. |
| Large files fail to upload / time out | Upload limits or proxy buffering too low | Raise `nextcloud_max_upload_size` and the PHP `upload_max_filesize`/`post_max_size`; ensure `fastcgi_request_buffering off` and a long `fastcgi_read_timeout`. |
| Admin overview shows "missing indices" or pending migrations | Schema changes from an upgrade not applied | Run `occ db:add-missing-indices` (and `occ db:add-missing-columns`); for a stalled upgrade run `occ upgrade`. |
| 403/permission errors writing files | Data directory ownership/permissions wrong | Ensure the data dir is owned by the system user with directories `0750` and files `0640`, and lives outside the web root. |

## A troubleshooting workflow

1. **Check [Health](../../platform/hosts/health.md)** - confirm the host is up and not out of CPU, memory or disk; a full data disk is a common, silent cause of failures.
2. **Read the relevant log** - start with `data/nextcloud.log` (or the admin Logging view), then the Nginx error log and PHP-FPM log for the failing request.
3. **Check the last deploy** - review [History](../../platform/hosts/revisions.md); if a recent change broke the site, revert and [re-publish](../../platform/hosts/publishing.md) the previous working revision.
4. **Verify services are running** - confirm PHP-FPM, the database and Redis are up on the [Services](../../platform/hosts/services.md) tab, since Nextcloud needs all three.

> [!WARNING]
> Always run `occ` as the system user (not root) from the `public_html` directory. Running it as root corrupts file ownership and can break the installation.

## Getting help

If you are stuck after working through the steps above, see the general [platform troubleshooting](../../platform/troubleshooting.md) guide. You can also contact [Support](../../platform/support.md) with the relevant log excerpts and the time the issue occurred.

## Related

- [Deploy Nextcloud](deploy.md)
- [Nextcloud best practices](best-practices.md)
- [Health](../../platform/hosts/health.md)
- [Support](../../platform/support.md)