Nextcloud upgrades can fail for several reasons: PHP timeouts, insufficient memory, file permission issues, or interrupted downloads. When an upgrade fails, Nextcloud usually gets stuck in maintenance mode and shows an error page.

Common Error Messages

  • “Nextcloud is in maintenance mode” – the upgrade started but didn’t finish
  • “An unaccelerated memory limit error occurred” – PHP ran out of memory
  • “Exception during upgrade” – a specific step in the upgrade process failed
  • “Updates between multiple major versions are unsupported” – you’re trying to skip versions
  • “Your web server is not properly set up to resolve /ocs-provider/” – a LiteSpeed rewrite issue. See Fix Nextcloud OCS Provider Error on LiteSpeed

Fix 1: Complete the Upgrade via Command Line

The most reliable fix. SSH into your server and run the upgrade manually:

  cd /var/www/nextcloud    # or your Nextcloud install path
sudo -u www-data php occ upgrade

If you’re on shared hosting with cPanel:

  cd ~/public_html/nextcloud
php occ upgrade

This picks up where the failed upgrade left off and usually completes successfully.

Fix 2: Disable Maintenance Mode

If the upgrade completed but Nextcloud is still stuck in maintenance mode:

  sudo -u www-data php occ maintenance:mode --off

Or edit config/config.php directly:

  // Change this line:
'maintenance' => true,
// To:
'maintenance' => false,

Fix 3: Increase PHP Memory and Timeout

If the upgrade failed due to resource limits, increase them before retrying:

Via php.ini or .user.ini

Create or edit .user.ini in your Nextcloud root directory:

  memory_limit = 512M
max_execution_time = 300
upload_max_filesize = 16G
post_max_size = 16G

Via cPanel

  1. Go to cPanel > MultiPHP INI Editor
  2. Select your domain
  3. Set memory_limit to 512M
  4. Set max_execution_time to 300
  5. Save

Then retry the upgrade:

  sudo -u www-data php occ upgrade

Fix 4: Fix File Permissions

Wrong file permissions are a common cause of upgrade failures:

  cd /var/www/nextcloud

# Set correct ownership
sudo chown -R www-data:www-data .

# Set correct permissions
sudo find . -type f -exec chmod 644 {} \;
sudo find . -type d -exec chmod 755 {} \;

# Make the data directory more restrictive
sudo chmod 750 data/

Then retry the upgrade.

Fix 5: Manual Upgrade (Nuclear Option)

If the built-in updater keeps failing:

  1. Back up everything first:

      # Back up the database
mysqldump -u nextcloud_user -p nextcloud_db > nextcloud_backup.sql

# Back up the Nextcloud directory
cp -r /var/www/nextcloud /var/www/nextcloud_backup

  2. Download the target version:

      wget https://download.nextcloud.com/server/releases/nextcloud-XX.X.X.tar.bz2
tar -xjf nextcloud-XX.X.X.tar.bz2

  3. Replace files (keep config and data):

      # Remove old files (NOT config or data)
rm -rf /var/www/nextcloud/core
rm -rf /var/www/nextcloud/apps
rm -rf /var/www/nextcloud/lib
rm -rf /var/www/nextcloud/resources
rm -rf /var/www/nextcloud/settings
# ... (keep config/ and data/)

# Copy new files
cp -r nextcloud/* /var/www/nextcloud/

# Fix ownership
chown -R www-data:www-data /var/www/nextcloud

  4. Run the upgrade:

      sudo -u www-data php occ upgrade
sudo -u www-data php occ maintenance:mode --off

Skipping Major Versions

Nextcloud does not support skipping major versions. If you’re on version 25 and want to reach version 29, you must upgrade step by step:

  25 → 26 → 27 → 28 → 29

Each major version upgrade must complete before starting the next one. Check your current version:

  sudo -u www-data php occ status

Preventing Future Issues

  • Enable automatic background updates in Nextcloud’s admin settings for minor versions
  • Always back up before upgrading (database + files)
  • Don’t skip major versions – upgrade one at a time
  • Check the Nextcloud admin docs for version-specific notes before upgrading
  • Test on a staging copy first if you’re running a production instance

Last updated 22 Apr 2026, 14:21 +0200. history

Was this page helpful?