Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsA failed Nextcloud update is usually recoverable, but the correct fix depends on the stage that stopped: prerequisite checks, file replacement, backup creation, or database and app migration. Record the exact error, keep the instance in maintenance mode, make a complete backup, then correct the reported cause before retrying. Never treat the updater’s code snapshot as a full backup or switch maintenance mode off before you know whether the new code and migrations are complete.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
First identify the stage that failed
Nextcloud’s updater is a sequence, not one operation. An error about permissions needs a different remedy from an exception raised during a database migration. The updater screen, command output and Nextcloud log together show where the process stopped.
As an Amazon Associate I earn from qualifying purchases.
| Stage | Typical symptom | What it means | First action |
|---|---|---|---|
| Release and requirement checks | Target version is not offered, or a prerequisite is reported as unsupported | The proposed release path or server environment may not be supported | Check the target release’s supported upgrade path and system requirements before changing files |
| File and permission checks | “Files are not writable,” ownership errors, or a named path cannot be changed | The web-server account cannot modify a required installation path | Check the deployment’s owner, group and permissions; do not retry blindly |
| Expected-file or integrity checks | An unexpected, missing or modified file is listed | Leftover or altered files could make code replacement unsafe | Compare the named path with the matching release and use the documented manual-upgrade method if necessary |
| Updater backup | The internal backup cannot be created or verified | The updater cannot safely retain its code snapshot | Check storage, access and the backup path, then create your own complete backup |
| Code replacement | New files were unpacked but the updater stopped before migration | The code may now be at the target version while the database is not | Keep maintenance mode enabled and determine whether occ upgrade is the remaining phase |
| Database or app migration | An exception appears while upgrading the database or apps | A schema change or app migration failed | Read the exact exception in the Nextcloud log, correct that cause, and rerun the migration |
Save a screenshot or copy of the updater message before making changes. If the command line was used, save the complete output, including the first exception and any path or app name. A later generic message such as “upgrade failed” is less useful than the original stage-specific detail.
Protect the installation before another attempt
Nextcloud’s administration guidance says to maintain regular backups and make a fresh backup before every upgrade. Do this before repairing permissions, replacing files or rerunning a migration. A restore point lets you return to the pre-upgrade state instead of trying to guess which mixture of old and new files is present.
#1 Best Overall
- Easily store and access 2TB to content on the go with the Seagate Portable Drive, a USB external hard drive
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
What a complete backup contains
- Database: export the entire Nextcloud database with the database engine’s supported dump procedure, including schema, data and privileges needed to restore it.
- Data directory: copy the directory that contains users’ files, versions, trash and other stored data. Confirm that the copy includes hidden files and preserves ownership and timestamps where your restore procedure requires them.
config.php: preserve the configuration file, including the database connection, data-directory location, trusted domains and encryption settings if encryption is enabled.- Application and deployment files: retain any package, container, Snap or manually installed files required to recreate the same release and PHP/runtime environment.
Keep the backup on storage independent of the server. An external hard drive or SSD can hold a local copy, but it should not be the only copy if the server and the drive can fail together. Test that you can read the dump and restore a representative file; a backup that cannot be read is not a recovery plan.
Why the updater backup is not enough
The updater’s internal code backup is stored under its updater backup path. It is a supplemental snapshot of code, not a full restore point: it does not include the data directory or database. It therefore cannot by itself restore users’ files or undo a schema migration. Keep it, but still make the three-part backup above.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Check the release path and system requirements
A major-version upgrade is supported only along the paths documented for the versions involved. Do not assume that a direct jump from an old release to the newest release is valid. Review the requirements for the target version and each required intermediate step: supported PHP version, database engine and version, web server, extensions, and available disk space can change between releases.
How to decide whether the target is valid
- Record the currently installed Nextcloud version and the target version shown by the updater.
- Read the version-specific upgrade instructions and identify whether an intermediate major release is required.
- Compare the target release’s system requirements with the actual server, including PHP modules and database capabilities.
- Check free space in the installation, temporary and updater-backup locations. Code extraction and database operations may need more space than the final installation size.
- If the path or requirements are unsupported, stop. Restore the backup if code has already changed and plan an upgrade through the documented sequence.
Skipping a major version is not a harmless shortcut. If the documentation does not list the jump as supported, use the required intermediate release rather than forcing the updater or copying files from an unrelated version.
Fix “files are not writable” and ownership errors
The updater checks that files needing modification can be written by the account that runs Nextcloud. On a typical Ubuntu web-server installation this is often www-data, but the correct account depends on the web server, PHP-FPM pool, container image, Snap confinement or hosting panel. Use the account that actually serves the instance, not a guessed username.
Rank #2
- Easily store and access 5TB of content on the go with the Seagate portable drive, a USB external hard Drive
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
Check the exact paths first
- Read the error’s full path. It may identify the Nextcloud directory, an app directory, the updater directory or a temporary location.
- Inspect the owner, group and permission bits for that path and its parent directories.
- Confirm that the filesystem is mounted read-write and that quotas, ACLs or security policies are not denying access.
- Check that the partition has free space and that no read-only error appears in the system log.
Correct ownership and permissions using the deployment’s documented procedure. Avoid making the entire server filesystem world-writable and avoid changing permissions recursively across unrelated directories. A broad change can expose configuration secrets or damage a package-managed installation.
Run commands as the web-server account
For a conventional Ubuntu installation, a documented pattern is:
sudo -E -u www-data php occ maintenance:mode --on
sudo -E -u www-data php occ upgradeReplace www-data, the current directory and the PHP executable with the values used by your deployment. In a container, run the command inside the application container. In a Snap or package-managed installation, use that package’s documented command wrapper instead of mixing host paths and a system PHP binary. The goal is consistency: the same user and runtime that serve Nextcloud should perform the migration.
Repair unexpected, missing or modified files
Before replacing code, the updater checks that the installation contains the files it expects. An error may name a file that was edited locally, left behind by an old app, removed accidentally or supplied by a different release.
Use the named path as evidence
- Write down the exact path and compare it with the file list for the installed release.
- Determine whether the file belongs to Nextcloud core, a first-party app, a third-party app or local customization.
- Restore a core file from the matching release archive or restore the installation from the pre-upgrade backup.
- If local modifications are intentional, preserve them outside the installation and follow the documented manual-upgrade process rather than asking the updater to overwrite them.
Do not delete every file reported as “unexpected.” Removing a configuration file, app directory or data path can make recovery harder. If the installation has accumulated many mismatched files, a clean manual deployment of the supported release, followed by the documented migration and configuration steps, is safer than deleting paths one at a time.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
- Easily store and access 1TB to content on the go with the Seagate Portable Drive, a USB external hard drive.Specific uses: Personal
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop. Reformatting may be required for Mac
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
When the updater’s backup stage fails
A backup-stage failure means the updater could not create or verify its own code snapshot. Common practical causes include insufficient space, an unwritable updater-backup directory, a full filesystem or a path that is unavailable inside a container or restricted package environment.
Checks before retrying
- Verify free space on the filesystem containing the Nextcloud code and the updater backup path.
- Confirm that the web-server account can create, read and remove a test file in the relevant directory.
- Check that the backup path is mounted and writable in the same environment where the updater runs.
- Review filesystem, quota and service logs for I/O or read-only-mount errors.
- Make the complete database, data-directory and configuration backup described above.
Even after the updater’s internal snapshot works, retain your independent backup. The internal snapshot covers code only and is not a substitute for a restore of user data and database state.
Review third-party apps before upgrading
Third-party apps can block an upgrade when they depend on removed APIs, an unsupported PHP version or a database schema that no longer matches the new core release. Nextcloud’s administration guidance is to review third-party apps for compatibility with the new release and disable incompatible apps before upgrading.
Safe app sequence
- List installed apps and identify which are not shipped with the target Nextcloud release.
- Check each app’s release notes or compatibility information for the exact target major version.
- Disable apps that are unsupported, unmaintained or not needed for the upgrade. Do not remove their data unless the app’s documentation explicitly requires it.
- Complete the core upgrade and all database migrations.
- Review the log and the app’s compatibility information again, then enable only apps confirmed to work with the installed release.
If a migration exception names an app, leave that app disabled while you correct its version or configuration. Re-enabling it repeatedly can reproduce the same failure and obscure the first useful exception.
Recommended Free Tools
Run occ upgrade when code replacement finished
The migration phase upgrades the database schema and apps after code replacement. Nextcloud documents that occ upgrade runs only this migration phase; it does not perform the entire file-download and code-replacement process.
Rank #4
- Easily store and access 4TB of content on the go with the Seagate Portable Drive, a USB external hard drive.Specific uses: Personal
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
Command and prerequisites
sudo -E -u www-data php occ upgradeRun it from the Nextcloud installation directory, with the real web-server account and PHP runtime for the deployment. Keep maintenance mode enabled while it runs. The command may take time for large databases, and interrupting a schema change can leave the instance incomplete; use a reliable terminal session and do not start several migration processes at once.
Read the exact exception
If the command fails, open the Nextcloud log and locate the exception generated at the same time. The log is the authority for identifying the failing migration or app. Record the exception class, message, app identifier, database table or column, and any preceding warning that explains the condition.
- A missing column, index or primary key can indicate an unfinished schema change or a database user lacking the required privilege.
- An app name in the exception points to an app compatibility or app-code problem; keep that app disabled while resolving it.
- A database connection or timeout error requires checking credentials, server availability, limits and transaction state before rerunning.
After correcting the logged cause, rerun occ upgrade. Do not repeatedly run it without changing anything; repeated blind attempts can make the log harder to interpret and do not repair the underlying condition.
Long-running database changes
Nextcloud notes that some lengthy database changes, such as adding missing columns, indices or primary keys, can be run separately after the upgrade. Follow the instructions for the specific release and database engine, and take another database backup before manual schema work. Never invent SQL based only on a shortened error message.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Understand maintenance mode instead of disabling it blindly
The updater enables maintenance mode to prevent users from writing data while code and schema are out of sync. Nextcloud documents that maintenance mode can remain enabled when code replacement or occ upgrade fails. That state is a safety signal, not proof that the upgrade is complete.
Best Value
- High capacity in a small enclosure – The small, lightweight design offers up to 6TB* capacity, making WD Elements portable hard drives the ideal companion for consumers on the go.
- Plug-and-play expandability
- Vast capacities up to 6TB[1] to store your photos, videos, music, important documents and more
- SuperSpeed USB 3.2 Gen 1 (5Gbps)
When to leave it enabled
- The target code has been installed but database migrations have not completed.
- The updater stopped after an exception and you have not confirmed which phase succeeded.
- You are restoring files or database state from the pre-upgrade backup.
Return the instance to normal service only after success
Once the underlying error is fixed, migrations complete successfully and the installed version is confirmed, use the documented maintenance command with the correct service account. On a typical Ubuntu installation, the command pattern is:
sudo -E -u www-data php occ maintenance:mode --offUse the actual account, path and package-specific wrapper for your environment. If the site still reports a pending upgrade, shows schema errors or logs exceptions, leave maintenance mode enabled and continue diagnosis instead of exposing a partially upgraded instance.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteA safe recovery workflow
- Record the failure. Save the updater screen, command output, version numbers, named paths and the relevant Nextcloud log entries.
- Stop blind retries. Confirm the target release path and system requirements, including runtime and database versions.
- Create a complete backup. Dump the database, copy the data directory and preserve
config.php; keep a copy away from the server. - Confirm the deployment type. Decide whether the instance is package-managed, containerized, a Snap, or a manual installation, because file locations, users and commands differ.
- Check storage and access. Verify free space, writable mounts, ownership, permissions, quotas and the updater-backup path.
- Resolve file integrity errors. Restore named core files from the matching release or use the supported manual-upgrade procedure; do not delete files indiscriminately.
- Disable incompatible third-party apps. Keep them disabled until the core upgrade and migrations finish.
- Continue the correct phase. If code replacement completed and only migration remains, run
occ upgrade. If a prerequisite failed, rerun the updater only after fixing that prerequisite. - Use the log to fix migration failures. Correct the exact database or app exception, then rerun the migration once.
- Validate and reopen service. Confirm the reported Nextcloud version, inspect logs, test login and file access, and disable maintenance mode only after the upgrade is coherent.
Choose the recovery route that matches the failure
| Route | Changes | Backup and reversibility | Access and deployment fit | Downtime |
|---|---|---|---|---|
| Fix prerequisite and rerun updater | Updater checks and, later, core code | Requires a fresh complete backup; reversible by restoring code, database and data | Works when the existing package, container, Snap or manual deployment remains supported | Maintenance mode covers the retry and migration |
Run occ upgrade manually |
Database schema and app migrations only | Keep a database backup; code must already match the target release | Requires shell access and the correct service account and PHP runtime | Maintenance mode remains on during migration |
| Restore the pre-upgrade backup | Returns code, database and data to the known state you backed up | Most reversible when all three components are available and tested | Requires restore privileges and enough storage; follow the database engine’s restore procedure | Downtime lasts through restore and validation |
| Clean manual deployment along a supported path | Replaces core code while preserving or reconnecting configuration and data | Use the complete backup; preserve custom changes outside the code tree | Best for persistent file-integrity problems, but requires administrator-level control | Maintenance mode stays on until migrations and checks finish |
Do not choose a route solely because it is faster. A manual code replacement that ignores the supported release path can leave a database that cannot be migrated, while running occ upgrade against old code can produce misleading errors.
Validate the installation after a successful upgrade
- Check the Nextcloud administration page or command output for the expected installed version.
- Review the log for new exceptions, especially during the first request after maintenance mode is disabled.
- Sign in with an administrator account and test a normal user account.
- Open existing files, upload a small test file, download it and confirm that sharing and background jobs behave as expected.
- Confirm that the database is reachable and that scheduled jobs run under the intended account.
- Re-enable only third-party apps confirmed compatible with the installed release.
- Retain the pre-upgrade backup until the instance has operated normally long enough for your retention policy.
When local troubleshooting should stop
Escalate to your hosting or systems administrator when you cannot obtain a complete backup, lack database or shell access, the filesystem is read-only, or the supported release path requires a runtime change you cannot perform. Provide the exact Nextcloud version, target version, deployment type, updater stage, command output and relevant log exception. That information lets an administrator distinguish a permissions repair from a database restore or a required staged upgrade.
The key decision is not whether to force the updater past an error. It is whether the code, database and apps are in a state that the documented release path supports. Preserve that state with a complete backup, keep maintenance mode on while it is incomplete, and use the log to select the smallest safe repair.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
