You finish a Nextcloud update, but everyone still sees the maintenance page. Or an upgrade was interrupted and the site never came back online. The OCC command to disable maintenance mode is short, but running it before checking the upgrade state can expose an unfinished installation. Start by confirming which Nextcloud instance you are administering and whether a database upgrade is still required.
Illustrative example: Imagine a small office running Nextcloud on Ubuntu. A scheduled update was interrupted after new code files were deployed, and the web page still says the server is in maintenance mode. This example is hypothetical; it is a thread for applying the checks below, not a report of a real incident or test.
Nextcloud maintenance mode blocks normal user access while an administrator performs work such as an upgrade or backup. It is a server-wide state, so users may see a maintenance notice even when the web server itself is running. Nextcloud’s current Administration Manual documents the OCC command for enabling or disabling this mode and notes that users may need to refresh their browser after it is turned off.
For the illustrative office, the maintenance page alone does not tell the administrator whether the upgrade finished. They need to query Nextcloud itself before changing the mode.
The command examples here are for a conventional archive-based Nextcloud installation on Ubuntu, with the code in /var/www/nextcloud and the web-server account named www-data. Nextcloud documents that occ lives in the installation directory and must be run as the HTTP user; on Debian and Ubuntu that user is normally www-data.
For this standard layout, enter the installation directory:
cd /var/www/nextcloudIf your Nextcloud files are elsewhere, use that actual path. Snap, Docker, appliances, and managed hosting use different command wrappers or filesystem layouts. Do not run the host command against a container installation or assume the archive path applies to those deployments. Follow the update instructions for your installation method, as described in the official Nextcloud upgrade guide.
In the office example, the administrator checks the deployment notes and confirms that this is an archive installation before running OCC.
Run OCC as the web-server account so that files and configuration retain their expected ownership:
sudo -E -u www-data php occ statusLook at the maintenance and needsDbUpgrade fields. Current versions also support a status exit code:
sudo -E -u www-data php occ status -e
echo $?The documented exit codes are useful when output is being checked by a script: 0 indicates normal operation, 1 means maintenance mode is enabled, and 2 means occ upgrade is required. The plain status output should also be reviewed; do not use the exit code alone to decide whether to reopen the site.
For the hypothetical office server, if needsDbUpgrade is true or status -e returns 2, the right next step is to complete the upgrade, not simply turn maintenance mode off.
If a Nextcloud code upgrade was intentionally deployed and OCC reports that the database upgrade is needed, take or verify a current backup of the database, configuration, and data before proceeding. Then run the documented command from the installation directory:
sudo -E -u www-data php occ upgradeRead the command output and wait for it to finish. Do not interrupt it because the web page appears unchanged while migrations are running. The built-in updater may leave maintenance mode enabled when the code replacement or occ upgrade fails. If the updater itself did not finish replacing the code, follow its log and resume the appropriate updater process for your installation rather than skipping directly to maintenance:mode --off. Nextcloud’s built-in updater instructions explain the update phases and identify the updater log as a diagnostic resource.
In the example, the office administrator would only run occ upgrade if the status indicates that the database migration remains pending and the expected new code is in place. If the command reports an error, they keep the server unavailable and investigate that error first.
When the upgrade is complete and status no longer says a database upgrade is required, disable maintenance mode using Nextcloud’s built-in command:
sudo -E -u www-data php occ maintenance:mode --offA successful command reports that maintenance mode has been disabled. This is the supported way to change the mode for a standard installation; it also keeps the state change within Nextcloud’s own command interface rather than relying on manual edits to config.php.
The example office administrator now runs this command only after the migration is complete. If no upgrade was in progress and status showed the installation was otherwise ready, the same command can clear a maintenance flag left on after planned maintenance.
Check the status again:
sudo -E -u www-data php occ status
sudo -E -u www-data php occ status -eFor a ready installation, expect maintenance: false, needsDbUpgrade: false, and a normal exit code of 0. Then open the site from a fresh private browser window and sign in with an administrator account. Ask one regular user to refresh their browser before assuming their session is still blocked.
In the illustrative scenario, success means both the OCC status and the web page agree that the instance is back online. The hypothetical example does not claim that any command was actually run or that a real server was repaired.
Confirm that you ran OCC against the same installation that serves the URL. This matters on a load-balanced deployment, a Docker host with multiple containers, or a server with old and new Nextcloud directories side by side. Check the actual document root or container path and query the instance behind the affected URL. If each web node has its own configuration, confirm that all nodes share the intended configuration and database.
If the correct instance reports maintenance disabled, compare the page from the server’s origin with the public URL. A reverse proxy or cache may be serving a stale response. Clear or bypass that cache only after verifying which layer returned the maintenance page.
Check that the command uses the PHP CLI version and required extensions compatible with the web installation. Nextcloud notes that APCu is disabled by default for CLI PHP and can cause OCC errors when APCu is configured as a local cache. Its manual documents enabling apc.enable_cli in the CLI PHP configuration or adding --define apc.enable_cli=1 to the PHP command when appropriate:
sudo -E -u www-data php --define apc.enable_cli=1 occ statusUse this only when the error indicates the APCu CLI issue; it is not a general fix for all PHP errors. Also verify that the command runs as the correct web user and from the correct installation directory.
Do not force the maintenance flag off to hide this status. Recheck the updater output and logs, verify that the correct Nextcloud code release is installed, and complete the supported upgrade procedure for your installation type. The official OCC system and maintenance command reference documents maintenance:mode, status, and the command-line upgrade.
Disabling maintenance mode allows users back into the instance, so confirm the database upgrade and any required code replacement are complete first. Avoid manually deleting updater files or editing the maintenance setting in the configuration file as a first response; doing so can hide the symptom without completing the work that triggered the mode.
For the hypothetical office, the safe decision is straightforward: verify the correct installation, inspect status, complete any required upgrade, then run maintenance:mode --off and verify both OCC and the browser. If the upgrade cannot be completed cleanly, leave maintenance mode on and troubleshoot from the updater log or installation-specific recovery procedure.
Compare seven tools that support or complement WSUS, from Microsoft’s native console and diagnostics to third-party patch publishing and remote deployment.
Compare six Windows system monitoring tools for server health, application visibility, and alerting, with current notes on deployment and licensing.
Compare seven Wake-on-LAN tools by features and availability, including free utilities, network-admin suites, and 2021 picks that have since been retired.
Compare nine ping tools for quick reachability checks, subnet discovery, TCP tests, and latency monitoring, with guidance on which one fits your network task.
Compare the best TFTP servers for Windows, Linux, and macOS, including SolarWinds, Tftpd64, tftpd-hpa, atftpd, haneWIN, and dnsmasq.
Compare five Microsoft Access alternatives for desktop, SQLite, no-code, and browser-based database work, with strengths, limits, and best-fit use cases.
Compare open-source and closed-source monitoring tools by cost, support, customization, security, and current options including Zabbix, Nagios, PRTG, and more.
Understand how ingress and egress describe incoming and outgoing traffic, why direction depends on the network boundary, and how to monitor bandwidth and spot risky data transfers.
Compare six free syslog servers and collectors for Windows and Linux, including GUI tools, open-source options, search, alerting, and secure transport.
See what Microsoft IIS does, how its request pipeline and application pools work, and when Apache, NGINX, or Caddy may fit your web server needs better.
