Troubleshooting Nextcloud

Diagnose Nextcloud on TurboStack - trusted_domains errors, stuck maintenance mode, background cron, Redis locking, upload limits and missing indices - with log locations and a workflow.

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 tab for service status and resource alerts, and review recent deploys in History.

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 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 - 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; if a recent change broke the site, revert and re-publish the previous working revision.
  4. Verify services are running - confirm PHP-FPM, the database and Redis are up on the Services tab, since Nextcloud needs all three.

Getting help

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

© 2026 Hosted Power — TurboStack