Self-Hosting

Nextcloud is slow or sync is failing

Make Nextcloud fast and reliable — the real fixes operators apply (system cron, APCu+Redis, missing DB indices, PHP memory_limit/OPcache) and the maintenance-mode backup that actually restores.

Problem summary

'Nextcloud is slow' is almost always one of a small set of misconfigurations the admin overview already warns about: background jobs left on AJAX instead of system cron, missing memory caching (APCu local + Redis for distributed cache and file locking), missing database indices after an upgrade, and a too-small PHP `memory_limit`/OPcache. Sync-client failures trace to those same warnings plus reverse-proxy/cert/`trusted_domains` issues. Backup is its own discipline: you need config + the data directory + the database, taken in maintenance mode, or the restore won't be consistent.

Operator snapshotEvidence first

First proof

Open Administration → Overview and read the setup-check warnings.

Screen to open

sudo -u www-data php occ db:add-missing-indices

Expected signal

The page lists the exact issues (cron, cache, indices, OPcache, headers).

Stop boundary

A backup missing any of the three cannot be restored.

Layer path

1Nextcloud 'slow' is rarely the hardware — it's a short list of misconfigurations the admin overview's setup checks already flag: AJAX background jobs, missing memory cache, missing DB indices, and a small PHP memory_limit/OPcache.

2Background jobs on AJAX only run when someone is browsing, so housekeeping never completes; system cron fixes it. Memory caching (APCu local + Redis distributed/file-locking) is what makes the UI feel fast.

3Sync-client failures usually trace to the same overview warnings, plus reverse-proxy/TLS or trusted_domains issues, or a server stuck in maintenance mode after a failed upgrade.

4Backup is a distinct discipline: config + data directory + database, taken in maintenance mode so they're consistent — and you cannot restore without all three.

Runbook

Step-by-step runbook

Start here. Do each check in order, compare it to the expected result, and stop when the evidence explains the failure or the safe stop point applies.

Read the overview warnings

Check: Open Administration → Overview.

Expected result: You have the exact list of misconfigurations.

If not: If the page itself is slow/erroring, fix PHP memory_limit first.

Fix background jobs + cache

Check: Set system cron, add APCu + Redis, set apc.enable_cli=1.

Expected result: Jobs run on schedule and the UI is responsive.

If not: If occ still segfaults, APCu CLI isn't enabled.

Add missing DB indices

Check: Run the three occ db:add-missing-* commands.

Expected result: Index warnings clear; queries speed up.

If not: Re-run after every major upgrade.

Resolve client/TLS issues

Check: Confirm maintenance is off, trusted_domains is correct, TLS chains.

Expected result: Clients sync without errors.

If not: Fix proxy headers / cert warning if clients still fail.

Back up config + data + database

Check: In maintenance mode, copy config/, data/, theme/ and dump the DB.

Expected result: You have a consistent, complete backup set.

If not: Never back up data and DB out of sync.

Safe stop: A backup missing any of the three cannot be restored.

Prove the restore

Check: Restore the set to a scratch instance; run data-fingerprint if older than clients.

Expected result: The scratch instance boots and logs in with your data.

If not: If clients churn, data-fingerprint wasn't updated.

Decision tree

If: Overview shows missing indices after an upgrade

Then: The DB is doing full scans where an index should exist.

Action: Run occ db:add-missing-indices (and add-missing-columns / add-missing-primary-keys).

If: occ segfaults or OOMs from the CLI

Then: APCu isn't enabled for CLI.

Action: Set apc.enable_cli=1 in the PHP CLI config and retry.

If: Fatal 'Allowed memory size exhausted'

Then: PHP memory_limit is too low.

Action: Raise memory_limit to 512M+ and re-test the failing operation.

If: Desktop/mobile clients won't sync but the web UI works

Then: trusted_domains/TLS/reverse-proxy or maintenance mode.

Action: Confirm maintenance is off, the URL is trusted, and TLS chains; fix proxy headers.

If: Restored an old backup and clients behave oddly

Then: Clients don't know the data went backwards.

Action: Run occ maintenance:data-fingerprint, then occ files:scan, so clients reconcile.

Evidence

Evidence table

Symptom	Evidence to collect	Likely layer	Next action
Shares/activity update only when someone is logged in	Background jobs mode in admin settings	AJAX cron instead of system cron	Switch to system cron with a crontab entry as the web user.
UI sluggish, occ crashes from shell	APCu config + apc.enable_cli value	Missing memory cache / APCu CLI not enabled	Add APCu+Redis; set apc.enable_cli=1.
Random 'internal server error' on big operations	PHP error log for memory-exhausted fatals	PHP memory_limit / OPcache too small	Raise memory_limit and OPcache sizing.
Clients stuck, web UI fine	occ status (maintenance flag), trusted_domains	Maintenance mode left on / wrong trusted_domains	Clear maintenance mode; fix trusted_domains and proxy headers.
After a restore, clients delete or re-download everything	Whether data-fingerprint was updated post-restore	Backup older than client state	Run occ maintenance:data-fingerprint then files:scan.

Reference

Commands and settings paths

Add missing database indices after an upgrade

sudo -u www-data php occ db:add-missing-indices

Where: On the Nextcloud host as the web-server user

Expected: Indices are created; the overview warning clears.

Failure means: A DB error means credentials/permissions or an in-progress upgrade.

Safe next step: Also run db:add-missing-columns and db:add-missing-primary-keys.

Enter and leave maintenance mode for a consistent backup

sudo -u www-data php occ maintenance:mode --on # ... back up ... then --off

Where: On the Nextcloud host as the web-server user

Expected: Maintenance mode toggles; the site shows the maintenance page while on.

Failure means: If occ errors, PHP CLI/APCu or DB access is misconfigured.

Safe next step: Always turn it back off; a left-on flag breaks clients.

Dump the database (MariaDB)

mariadb-dump --single-transaction --default-character-set=utf8mb4 -u <user> -p <db> > nextcloud-db.sql

Where: On the DB host / container

Expected: A complete SQL dump is produced.

Failure means: An incomplete dump or charset errors mean the wrong engine flags or creds.

Safe next step: Pair the dump with the config/, data/, and theme/ folders in the same window.

Hardware boundary

Hardware and platform boundary

Change only when

Add Redis + APCu the moment the instance has more than one active user.
Move to PHP-FPM tuning and a real maintenance window once nightly jobs collide with usage.

Evidence that matters

System cron, APCu local cache, Redis for locking, and apc.enable_cli=1.
PHP memory_limit 512M+, healthy OPcache sizing, and all DB indices present.
A maintenance-mode backup of config + data + database, proven to restore.

Evidence that does not matter

Throwing CPU/RAM at a server whose only problem is AJAX cron and no cache.
Chasing a faster disk before the overview warnings are cleared.

Avoid

Leaving background jobs on AJAX 'because it works'.
Backing up the data directory without the database (or vice versa).
Leaving a stray *.config.php in config/ — it silently overrides live config.

Related tool

Use the linked tool to turn this runbook into a guided check for your exact setup.

NAS setup planner

Last reviewed

2026-06-03 · Reviewed by HomeTechOps. Built from 2026-06 research verified against the Nextcloud admin manual (backup, restore, server config parameters) and the current Hub version mapping. The operator differentiator is treating the admin-overview setup checks as the actual fix list and insisting on a maintenance-mode, all-three-components backup that is restore-proven.

Sources/assumptions

Assumes a manual / community-docker Nextcloud (PHP + MariaDB/PostgreSQL behind Apache or nginx/PHP-FPM); the All-in-One (AIO) appliance ships its own integrated Borg-based backup, so its mechanics differ.
Versions: as of 2026-06 the supported lines are v32 (Hub 25) and v33 (Hub 26), with v34 launching 2026-06-09 — always run the newest maintenance point. Performance/backup settings are stated from the Nextcloud admin manual.
occ commands are run as the web-server user (e.g. www-data); paths assume a standard /var/www/nextcloud install.

Source-backed checks

HomeTechOps turns official docs and conservative safety rules into a shorter runbook. These links are the source trail for the page direction.

Nextcloud admin manual: BackupUsed for the five backup components (config/apps/data/theme/database), maintenance mode, and the per-engine database dump commands.Nextcloud admin manual: RestoreUsed for the restore requirement (database + data + config together) and occ maintenance:data-fingerprint when the backup is older than client state.Nextcloud admin manual: Configuration parametersUsed for the maintenance flag, data-fingerprint, the maintenance_window setting, and the *.config.php auto-load-override trap.

Diagnostic rule

1. Check the simplest signal first.
2. Change one thing at a time.
3. Confirm the layer (app, container, network) before deep config.
4. Prove the restore; don't assume it.

FAQ

What's the single biggest Nextcloud speed fix?

Switch background jobs from AJAX to system cron, and add memory caching. AJAX jobs only run when someone's browsing, so housekeeping never finishes; a real cron entry (`*/5 * * * * php -f /var/www/nextcloud/cron.php` as the web user) fixes that. Then add APCu for local cache and Redis for distributed cache + file locking — and set `apc.enable_cli=1`, or `occ` will OOM/segfault. After any upgrade, run `occ db:add-missing-indices`. These are exactly what the admin-overview setup checks flag.

The admin overview warns about OPcache / memory — does that matter?

Yes, those warnings are real performance and reliability issues. Raise PHP `memory_limit` to 512M or more, enable OPcache and bump `opcache.memory_consumption` and `opcache.interned_strings_buffer` above the defaults, and add the missing DB indices/columns/keys it lists. A nearly-full OPcache or a 128M memory limit produces both sluggishness and outright 'Allowed memory size exhausted' fatals. See the Nextcloud server config reference.

How do I back up Nextcloud so it actually restores?

Put the server in maintenance mode first (`occ maintenance:mode --on`), then back up all of: the `config/` folder, the `data/` directory, the `theme/` folder, and the database (`mariadb-dump`, adding `--default-character-set=utf8mb4`). You cannot complete a restore without database + data + config together. If the restored backup is older than the desktop/mobile clients' state, run `occ maintenance:data-fingerprint` so clients detect the restore. Watch the trap that any stray `*.config.php` left in `config/` is auto-loaded and silently overrides live config. Full procedure: Nextcloud backup docs.