Nextcloud Database Error After an Update: What to Check First

If Nextcloud starts showing a “Database Error” exception after an update, check the underlying database error in nextcloud.log before changing any tables. Restore database connectivity first; if the update stopped partway through, finish it with occ upgrade and only then use the documented repair commands when the logs justify them.

Identify the actual failure

The browser message is a symptom, not a diagnosis. Nextcloud may be unable to reach MySQL/MariaDB or PostgreSQL, the database account may no longer authenticate, or the application code and schema may be at different upgrade stages. Nextcloud’s official troubleshooting reference recommends matching the failing request ID to the server log.

1. Record the time, the full browser error, and any displayed request ID. Do not publish private log entries without removing secrets and personal information.
2. Find the configured data directory in config/config.php. The default log file is data/nextcloud.log, but customized deployments may log elsewhere.
3. On a conventional Linux installation, check the recent entries and then the database service logs. Substitute your actual Nextcloud path:

sudo tail -n 100 /var/www/nextcloud/data/nextcloud.log
sudo journalctl -u mariadb --since '30 minutes ago'

The second command applies only to a host running MariaDB under systemd; use the PostgreSQL service or container logs for other deployments. Search for the exception’s SQLSTATE code and the first database-related cause rather than relying on the final stack-trace line.

The first three examples are covered in Nextcloud’s documented common errors. A missing-table message is not permission to create the table manually: identify the precise migration failure first.

Protect the instance before applying a fix

Before retrying migrations, preserve a restorable database backup together with Nextcloud’s configuration and data. The official backup procedure also includes custom apps and themes when present. Confirm that the backup belongs to the same point in time; a code-only backup cannot recover a partially changed database.

• Pause sync and background jobs during a recovery window where possible, especially when database writes or upgrades are involved.
• Keep a record of the old and new Nextcloud versions, the database engine/version, PHP version, and the update method.
• Do not delete database tables, import a blank schema, run random SQL from forums, or repeatedly restore only one component of a multi-part backup.

Commands below assume the common Debian/Ubuntu installation at /var/www/nextcloud, with www-data as its web-server account. Run occ as the appropriate HTTP user; package, Docker, Snap, AIO, and managed installations have different paths and execution methods. The occ command reference explains these requirements.

Restore database connectivity before migrating

Check the database service and Nextcloud connection settings

If the logs show connection refusal, an unreachable socket, or an unavailable server, first verify that the existing database service is running. These are alternative host-level checks, not a list to execute indiscriminately:

sudo systemctl status mariadb
sudo systemctl status postgresql

For a separate database server, also check DNS, firewall rules, the selected port, and network reachability from the Nextcloud application host or container. Inspect config/config.php for dbtype, dbhost, dbname, and dbuser. The configuration parameter reference explains hostnames, ports, and Unix socket syntax. Never paste dbpassword into public tickets or shell commands that expose it in history.

If a database password was rotated or credentials changed during deployment, correct that mismatch using your secret-management workflow. If the server reports too many connections, inspect active connections and the cause of connection accumulation before considering capacity changes. An index command will not cure a connection outage.

Check runtime compatibility after the update

A simultaneous PHP or database-server upgrade can break a previously working installation. Compare the target Nextcloud release with its official system requirements and release notes rather than assuming every currently installed driver and server version remains supported. As of the checked Nextcloud 35 documentation, PHP 8.3–8.5 is supported; the accepted database versions are documented there separately. Earlier releases have different limits.

Also confirm the PHP database driver required by your selected engine is enabled in both the command-line and web PHP environments. Do not blindly downgrade the database server after a schema migration: restore only from a compatible, consistent backup plan.

Complete or repair the interrupted Nextcloud upgrade

Once the database is reachable and a backup is secured, switch to the Nextcloud installation directory and check its state:

cd /var/www/nextcloud
sudo -E -u www-data php occ status

If Nextcloud reports that an upgrade is pending or incomplete, follow the supported upgrade path for the installed source and target versions. For a conventional manual installation, run:

sudo -E -u www-data php occ upgrade

Do not interrupt the command or run concurrent upgrade processes. Read its output: a successful migration is different from a database connection exception. Nextcloud’s manual upgrade documentation explicitly recommends occ upgrade when the web-based process stalls, and maintenance:repair if the upgrade path needs repair:

sudo -E -u www-data php occ maintenance:repair

Use maintenance:repair after analyzing the failure; it is not a substitute for fixing bad credentials, a stopped database, or a genuinely incompatible runtime. If occ upgrade fails on a specific SQL migration, save the exact exception and seek a version-specific fix or restore the complete matched backup rather than experimenting with manual DDL.

Handle schema warnings only after a successful upgrade

Some migrations are intentionally deferred. On a functioning instance, the admin overview may ask for optional columns, indices, or primary keys. These commands provide a dry-run preview when supported by that version:

sudo -E -u www-data php occ db:add-missing-indices --dry-run
sudo -E -u www-data php occ db:add-missing-columns --dry-run
sudo -E -u www-data php occ db:add-missing-primary-keys --dry-run

Run the corresponding command without --dry-run only if the logged problem or administrative check calls for it and the proposed change has been reviewed. These maintenance operations can take time on large databases. Nextcloud 35 additionally documents db:schema:check; do not assume it exists on older branches. See the database command reference for version-specific behavior.

Verify recovery and reopen access

1. Repeat sudo -E -u www-data php occ status. Confirm the installed version matches the intended release, there is no upgrade required, and no new fatal SQL exception is produced.
2. If maintenance mode is still on and the upgrade has completed successfully, disable it with sudo -E -u www-data php occ maintenance:mode --off.
3. Open the WebGUI, sign in, list files, and perform a small authorized upload and download. Watch nextcloud.log during these checks for fresh database exceptions.
4. Resume scheduled jobs and client synchronization, then review Administration settings for any remaining database warnings.

If the same database exception returns, stop repeated migrations and collect the request ID, SQLSTATE text, database-server log, version pair, and the failing occ output. That evidence determines whether the remaining issue is connectivity, incompatible software, or a specific failed migration. A successful login alone is not proof that every background task and database query works.