.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Saturday morning, I'd just moved my 4 GB VPS from PHP 8.3 to 8.5 ahead of a Nextcloud upgrade. Packages installed clean, php-fpm restarted without complaint, and the browser gave me a grey page: The server encountered an internal error and was unable to complete your request. Plus a suggestion to contact the administrator, who was sitting right there holding his coffee. That page is Nextcloud's catch-all 500. It means a PHP exception escaped, and it tells you nothing about which one, by design (leaking stack traces to visitors is worse). The actual error is always written down somewhere. The whole job is reading it instead of guessing, so this article is ordered by how often each cause turns out to be guilty on my instances and the ones I get asked to look at.
Step 1: read the real error in nextcloud.log
Before touching anything, open the log. On a manual install it's nextcloud.log in the data directory, JSON lines, one event per line:
sudo tail -n 20 /var/www/nextcloud/data/nextcloud.log | jq -r '[.time, .app, .message] | join(" ")'Nine times out of ten the newest lines name the culprit outright: a missing PHP class, a database connection refusal, a file permission denial. If the log location on your setup isn't obvious (Docker, snap and AIO all differ), where are the Nextcloud logs walks through every variant, plus the trick of raising loglevel when the default warning level stays quiet. One caveat before you trust an empty log: if PHP dies before Nextcloud boots (a config.php syntax error, a missing core module), nothing reaches nextcloud.log at all and the truth sits in the web server's error log instead, /var/log/apache2/error.log on my box. Check both. The logging configuration docs cover the knobs for both channels.
Step 2: a PHP module went missing after a PHP change
This was my Saturday, and it's the most common cause I see after any PHP version move. Each PHP version on Debian and Ubuntu has its own module set, so php8.5-fpm arrives with almost nothing while your carefully assembled 8.3 modules stay behind. Nextcloud then dies on the first database call because pdo_mysql isn't there. Check what the new version actually loads:
php -m | grep -E 'pdo_mysql|intl|gd|zip|curl|mbstring|xml|bcmath|gmp|apcu|redis|imagick'Anything missing, reinstall it for the new version:
sudo apt install php8.5-mysql php8.5-intl php8.5-gd php8.5-zip php8.5-curl \
php8.5-mbstring php8.5-xml php8.5-bcmath php8.5-gmp php8.5-apcu php8.5-redis php8.5-imagickThen restart the right service. Old and new php-fpm run in parallel happily, systemctl restart php8.5-fpm does nothing for you while Apache's proxy line still points at the 8.3 socket, and restarting 8.3 does nothing once you've switched the socket over. systemctl status 'php*-fpm' shows which ones are alive, and the SetHandler or proxy config in your vhost says which socket Apache actually uses. One more trap in the same family: php -m tests the CLI, php-fpm reads its own ini directory, so a module can exist for the CLI and still be absent in fpm. When the browser and the shell disagree, that's why.
Step 3: ownership broke during a restore or move
Second place goes to permissions, almost always right after a restore, a server migration or an rsync run as root. Nextcloud runs as the web user and needs to write to the data directory, the config directory and the apps directories. When it can't, some installs manage a clearer error, plenty just 500. The fix is ownership, applied to the right directories:
sudo chown -R www-data:www-data /var/www/nextcloud /var/www/nextcloud/dataAdjust the data path if yours lives outside the webroot (mine does, a separate volume). What I don't do is chmod -R 777, which turns a permission error into a world-writable install that Nextcloud will rightly complain about later. Ownership by the web user with the default modes (750 on directories, 640 on files is what my instance settled on) gives PHP everything it needs without opening the tree to every account on the box. After my last restic restore test I needed exactly one chown and nothing else.
Step 4: a typo in config.php
A hand-edited config.php with a missing comma or an unclosed quote kills the whole application before logging starts, which is the classic "empty nextcloud.log, angry Apache log" pattern from step 1. PHP will tell you directly:
sudo -u www-data php -l /var/www/nextcloud/config/config.phpEither No syntax errors detected or the exact line number of the problem. Takes five seconds and I run it after every manual config edit now, having once shipped a stray quote at 11 PM and spent twenty minutes suspecting the database instead.
Step 5: the database is down or the credentials rotated
If MariaDB crashed, ran out of disk or sits behind rotated credentials (password managers make rotating easy, updating config.php is the part people forget), every page is a 500. The occ command gives a fast verdict, because it uses the same config and the same connection path:
sudo -u www-data php /var/www/nextcloud/occ statusA healthy instance prints its installed state and version numbers. An unreachable database gets you a thrown exception instead, in the shape of a doctrine connection failure with the underlying SQLSTATE, connection refused when the server is down, access denied when the credentials are wrong. Those two phrasings point at different fixes: systemctl status mariadb and free disk space for the first, the dbuser and dbpassword lines of config.php for the second.
Step 6: memory limits and OPcache pressure
Intermittent 500s, heavier pages failing while light ones work, errors that arrive under load and vanish at night: that pattern smells like resource exhaustion rather than breakage. The log confirms it with allowed memory size exhausted messages or OPcache warnings. On my 4 GB box the settings that ended this class of problem were memory_limit = 512M in the fpm php.ini (512 MB is also what Nextcloud's own admin check asks for) and a modest OPcache bump, more interned strings buffer and more accelerated files than the PHP defaults. Set them in /etc/php/8.5/fpm/php.ini, restart php-fpm and watch the log for a day. If the OOM killer is taking php-fpm workers instead (check dmesg), that's a pm.max_children conversation, twelve is where I cap it on 4 GB.
Step 7: .htaccess and rewrites after a webroot move
Apache-specific, and reliably confusing: Nextcloud ships its rewrite rules in .htaccess, and those rules embed path assumptions. Move the install to a different directory or switch from a subdirectory to a subdomain, and requests start dying in rewrite loops or hitting paths that no longer exist. Two checks. The vhost needs AllowOverride All on the Nextcloud directory or the .htaccess is silently ignored, and after any path change this regenerates the rules for the current layout:
sudo -u www-data php /var/www/nextcloud/occ maintenance:update:htaccessThis is also my standing argument for Apache with PHP-FPM over nginx for Nextcloud: the project ships and maintains that .htaccess for you, while an nginx config is yours to keep in sync by hand forever.
Step 8: the error page isn't Nextcloud's at all...
Last check, and worth doing early when a reverse proxy is involved: read the page itself. Nextcloud's 500 is the grey page with the exact sentence quoted at the top of this article. A plain white page saying 502 Bad Gateway or 504 Gateway Time-out is the proxy talking, and it means the request died before Nextcloud ever saw it, so no amount of Nextcloud-side debugging will find anything. The proxy's error log will, usually a dead php-fpm socket, a stopped container or an upstream pointing at the wrong port. On nginx that's a tail -n 50 /var/log/nginx/error.log away, and connect-refused lines there name the exact upstream address to go check. If the log from step 1 shows nothing at the timestamp of the failure, this is where you look next.
Every 500 leaves a log line
Modules, permissions, config syntax, database, resources, rewrites, then the proxy. That order has sorted every 500 I've personally hit since around Nextcloud 24, and every one of them announced itself in a log before I fixed it. A special mention for upgrades: when the log talks about migrations or a required upgrade instead of an exception, you're in maintenance mode territory, which has its own exit procedure. And for everything that shows a specific message rather than the generic grey page, I keep a cheat sheet of common Nextcloud errors with the fix commands inline. The rule underneath all of it doesn't change: the log line always beats guessing. I've never once regretted the two minutes it takes to read it first.
