.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
This page is the cheat sheet I wish existed the first year I ran Nextcloud: the twelve errors and admin warnings I've hit most since version 24, each with what it means and the commands that fix it. Where a problem deserves a full walkthrough, I link it once at the relevant entry. Everything here is current against Nextcloud 34.0.3 on my own instance, a 4 GB VPS running MariaDB, Apache with PHP-FPM and Redis.
Two habits make every entry below faster. Read nextcloud.log before acting, the JSON lines in there usually name the cause outright, and where are the Nextcloud logs covers the locations for manual, Docker and snap installs. And check the admin overview (Administration settings, then Overview) after every change, it's where most of the warnings below surface, and the docs keep a general troubleshooting page for anything this list misses.
Access through untrusted domain
Nextcloud rejected the Host header of the request because it isn't listed in the trusted_domains array in config.php. Happens after adding a domain, changing IP or putting a reverse proxy in front. Quick fix, using the next free array index:
sudo -u www-data php /var/www/nextcloud/occ config:system:set trusted_domains 1 --value=cloud.example.comThe proxy variant (right domain in the browser, error anyway) and the Docker env var caveat are in the full guide to fixing the untrusted domain error.
This Nextcloud instance is currently in maintenance mode, which may take a while.
The maintenance flag is up, either because an upgrade is running (leave it alone, big filecache migrations take time) or because something raised it and died. Once you've confirmed nothing is mid-migration, the exit is:
sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --offIf that refuses, or occ reports a pending upgrade, work through the exit steps in Nextcloud stuck in maintenance mode before touching config.php by hand.
The server encountered an internal error and was unable to complete your request.
The generic 500. A PHP exception escaped and the page deliberately hides which one. The real error is in nextcloud.log, or in the Apache error log when PHP died before Nextcloud booted. The usual suspects in order: a PHP module missing after a version change (php -m | grep pdo_mysql), broken ownership after a restore, a config.php typo (php -l on the file), the database being down. My full diagnosis order with the commands for each is in how I debug the Nextcloud internal server error.
Nextcloud or one of the apps require upgrade - only a limited number of commands are available
You see this in the shell when the code on disk is newer than the database schema, typically after a package or image update, and occ locks itself down to upgrade-related commands until the migrations run. The fix is the thing it's asking for:
sudo -u www-data php /var/www/nextcloud/occ upgradeRun it in tmux over SSH, an interrupted migration is far worse than a slow one. When the same command fails repeatedly at one app's migration, disable that app with occ app:disable and rerun.
HTTP 423: "file.docx" is locked
The file locking table thinks someone still holds the file, usually leftovers from an interrupted sync or a crashed PHP worker rather than a real user. With database-backed locking the stale rows sit in oc_file_locks. Clear them with the instance quiesced, after a database backup:
sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on
mysql -u nextcloud -p nextcloud -e "TRUNCATE oc_file_locks;"
sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --offThat's the symptom fix. The real fix is moving locking to Redis, where locks expire properly, in config.php:
'memcache.locking' => '\OC\Memcache\Redis',
'redis' => [
'host' => '/run/redis/redis-server.sock',
'port' => 0,
],Use 'host' => 'localhost', 'port' => 6379 if you're not on the socket, and install the matching PHP extension (php-redis) or the config lines throw errors of their own. Redis stopped my lock errors completely, past one user I consider it non-negotiable, and the same server doubles as the distributed cache while it's there.
Last background job execution ran ... (the cron warning)
The admin overview complains that background jobs haven't run recently, hours or days ago in the message. It means your cron setup isn't firing: AJAX mode with nobody browsing, a webcron that stopped or a crontab entry that got lost in a migration. System cron wins every time, one line in the www-data crontab:
*/5 * * * * php -f /var/www/nextcloud/cron.phpThen set Background jobs to Cron in the admin settings and watch the timestamp on the warning reset within five minutes. Why this matters more than it looks (previews, trash retention and app queues all ride on it) is covered in Nextcloud cron and background jobs, along with the Docker patterns where crontab isn't available.
The reverse proxy header warning
The admin overview phrases it along the lines of the reverse proxy header configuration being incorrect, with a note about your IP address as visible to Nextcloud (the exact wording shifts between releases). It means Nextcloud sees the proxy's address as the client for every request, because trusted_proxies doesn't include the proxy:
'trusted_proxies' => ['10.0.0.2'],
'forwarded_for_headers' => ['HTTP_X_FORWARDED_FOR'],Fix it promptly, and for a second-order reason: while every request appears to come from one IP, Nextcloud's brute-force throttling punishes all users for one person's typos, and any log-based defense layered on top, CrowdSec for instance, bans your proxy instead of the attacker.
The PHP memory limit is below the recommended value of 512MB
Exactly what it says. Set memory_limit = 512M in the php.ini your web requests use, on my box that's /etc/php/8.5/fpm/php.ini, not the CLI one, then restart php-fpm. The warning clears on the next admin overview load. Below 512 MB things mostly work until a big preview or app update wants more, which is why the check exists. On a small VPS the limit interacts with your worker count, twelve php-fpm children at 512 MB each is the theoretical worst case, so I size pm.max_children with that multiplication in mind rather than raising limits blindly.
The PHP OPcache warning
The overview reports OPcache as not properly configured, sometimes naming a specific setting like the interned strings buffer (phrasing and thresholds vary across Nextcloud and PHP versions, so treat mine as a shape, and the message names the value it wants). These lines in /etc/php/8.5/fpm/conf.d/10-opcache.ini keep my instance quiet:
opcache.enable=1
opcache.interned_strings_buffer=32
opcache.max_accelerated_files=10000
opcache.memory_consumption=128
opcache.revalidate_freq=60Restart php-fpm after. If the warning persists, read which value it names now, newer releases occasionally raise the bar.
The data directory permissions warning
The overview warns that the data directory and its files are probably readable by other accounts on the system. The fix is tightening the directory to the web user:
sudo chown -R www-data:www-data /var/www/nextcloud/data
sudo chmod 0770 /var/www/nextcloud/dataAdjust the path if your data lives elsewhere (mine sits on a separate volume). Resist any urge in the other direction, loosening permissions to silence unrelated errors is how private files end up world-readable on shared boxes.
CSRF check failed
Login or form submissions bounce with this message when the request token doesn't match the session. Three causes cover nearly every case: cookies blocked or stale in the browser (private window test settles it in ten seconds), a reverse proxy or CDN stripping and caching headers it shouldn't touch, or broken session storage on the server, a full disk where PHP keeps sessions produces exactly this. Clear cookies first, then check df -h, then look at what the proxy does to the Cookie header. With a proxy involved, wrong overwriteprotocol settings also feed this error, the session cookie gets marked for HTTPS while Nextcloud thinks it's on HTTP.
The imagick SVG support warning
The admin overview notes that the PHP imagick module lacks SVG support. Harmless, and asked about constantly: it affects generating previews of SVG files and theming edge cases, nothing about your documents or photos. On Debian and Ubuntu the missing piece is the ImageMagick delegate package (on current Ubuntu, apt install libmagickcore-6.q16-6-extra), install it and restart php-fpm, or ignore the warning entirely. Of everything on this page, this is the one I've left unfixed on a test box for a year with zero consequences.
Beyond these twelve, the pattern generalizes. Every Nextcloud complaint worth reacting to lands in the log or the admin overview with a specific message, and searching that exact message beats describing symptoms every time. It's the reason each heading on this page is the string itself, and the reason my first move on any misbehaving instance is still tail -f on nextcloud.log while I reproduce the problem once.
