Fix Nextcloud Upgrade Errors

4 min read

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 link

• “Nextcloud is in maintenance mode” - the upgrade started but didn’t finish
• “Allowed memory size of … bytes exhausted” - 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 link

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
  

GoZen shared hosting has no shell, so you can’t run occ there. Open your Nextcloud URL in a browser instead: while an upgrade is pending, Nextcloud shows an update page with a Start update button. If that page times out, add a one-off job in cPanel > Cron Jobs that runs php ~/public_html/nextcloud/occ upgrade, and delete the job once it has run. If neither works, open a support ticket.

Either way, this picks up where the failed upgrade left off and usually completes successfully.

Fix 2: Disable Maintenance Mode link

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 link

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

Via php.ini or .user.ini link

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 link

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 link

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) link

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. Put Nextcloud in maintenance mode:

     cd /var/www/nextcloud
   sudo -u www-data php occ maintenance:mode --on
     

3. Download the target version:

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

4. Swap the old directory for the new one. Move the old install aside instead of deleting parts of it. Copying new files over old ones leaves stale files behind, and a * glob skips hidden files such as .htaccess and .user.ini:

     sudo mv /var/www/nextcloud /var/www/nextcloud-old
   sudo mv /tmp/nextcloud /var/www/nextcloud
     

5. Bring back your config, data and third-party apps:

     sudo cp -a /var/www/nextcloud-old/config/config.php /var/www/nextcloud/config/
   # Only if your data directory lives inside the install folder:
   sudo mv /var/www/nextcloud-old/data /var/www/nextcloud/
   # Third-party apps (copy any that the new release doesn't ship):
   sudo cp -a /var/www/nextcloud-old/custom_apps /var/www/nextcloud/ 2>/dev/null
   sudo chown -R www-data:www-data /var/www/nextcloud
     

   On older installs, third-party apps may sit in apps/ instead of custom_apps/. Copy any app folder from nextcloud-old/apps/ that’s missing in the new apps/.

6. Run the upgrade:

     cd /var/www/nextcloud
   sudo -u www-data php occ upgrade
   sudo -u www-data php occ maintenance:mode --off
     

Keep /var/www/nextcloud-old until you’ve confirmed everything works, then delete it.

Skipping Major Versions link

Nextcloud does not support skipping major versions. To go from major version N to N+3, you must upgrade step by step:

  N → N+1 → N+2 → N+3
  

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 link

• Watch the update notifications in Administration settings > Overview, and apply minor releases promptly with the updater or occ
• 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

Related Articles link

• Essential Linux Commands for VPS Users
• Database Management in cPanel
• Backups and Restores
• GoZen VPS Plans - Nextcloud runs best on a dedicated VPS