Nextcloud upgrade stuck: needsDbUpgrade stays true and oc_sharing_classmap already exists

You have started a Nextcloud upgrade. Processing stops with a table error, maintenance mode remains enabled, and needsDbUpgrade still shows true. You may already have restored an older container image or a database backup, yet the message keeps appearing. The priority now is to understand the current state and the first failure before introducing more changes.

This guide helps you distinguish a failed migration from a schema warning and gather the information needed for a controlled recovery. It deliberately includes only a read-only status command as an example. The appropriate repair path depends on the installation type, versions and available backups.

Does your error match this case?

The original case examined concerns Nextcloud running in Docker on a QNAP system with MariaDB. During the upgrade from 34.0.5 to 35.0.2, a SchemaException reports that the oc_sharing_classmap table already exists. The reporter describes maintenance mode remaining active and an upgrade still being required, even after restoring an earlier database backup and the older image. The visible discussion contains no confirmed resolution from that reporter. Q1

Look for the combination of symptoms, rather than a single word in the log:

• The upgrade explicitly reports a failure or an exception.
• Maintenance mode remains enabled, or the application continues to request an upgrade.
• needsDbUpgrade is shown as true.
• A message names a table that already exists, such as oc_sharing_classmap or oc_sharing_share.
• Access to files, shares or another function you rely on is not working as intended.

A similar container-related report describes an existing sharing table and a service that could not be brought back up. Its issue was closed as a duplicate. That status does not establish that the problem was fixed. Q5

Maintenance mode and a schema warning are different situations

When an upgrade actually fails, first establish the resulting state. A different situation is an upgrade that completes successfully and then reports differences between the expected and existing database schema. The project’s issue tracker also collects warnings of this kind from successfully upgraded instances. This does not mean that every table-related message in those reports represents a complete outage. Q6

The impact depends on your own use. If several colleagues cannot access shared documents they need, a business process is blocked. Access to personal files on a private installation can be just as urgent, but it does not automatically imply lost business revenue. Record exactly who needs which function and what alternative access is available.

What needsDbUpgrade tells you

The official status command shows information including the version, maintenance state and needsDbUpgrade. These values help describe the state of the installation. On their own, they do not explain why a particular table already exists. Q2

Matching version labels are not a complete verification either. The official description of the built-in updater separates replacement of program files from the subsequent migration of the database and apps. Q4 For diagnosis, this means recording both the state of the files and the migration step actually reached. Do not apply the built-in updater’s procedure to Docker, AIO, Snap or managed hosting without checking that it is appropriate.

Safe first steps: establish the state and prepare a recovery plan

1. Record what has happened in chronological order. Note the starting version, intended target version, when the attempt began and the first identifiable error message. Add any later changes, such as switching an image or restoring a database dump. For each action, record whether it completed. A short, accurate timeline is more useful than several unordered screenshots.

2. Identify the actual installation type. Are you using a particular container image, Nextcloud AIO, an archive installation, Snap or a service managed by your hosting provider? Record the available version or image identifiers and who operates the system. Nextcloud directs users to the appropriate upgrade instructions for each installation type. Q3 If you administer only the web interface, that already helps establish who needs to be involved; you do not need to try server commands intended for someone else’s setup.

3. Read the current status. A responsible administrator can run a command such as the following from the existing Nextcloud installation directory, using the service account or container context intended for that installation:

php occ status --output=json_pretty

This status command provides a structured overview. Q2 You may need to adapt the PHP invocation and the way you enter the existing service environment. A universal sudo or Docker command would be misleading across different installations. Save the output with a timestamp. Do not change maintenance or version fields to force the result you want.

4. Find the first failure in the relevant log. Preserve the output from the failed upgrade attempt and application or container logs from the same period. If you used the built-in updater, its updater.log can help identify the affected phase. Q4 Distinguish a table conflict from an explicit permissions error and from schema warnings reported afterward. Include only relevant extracts in a public request for help, sanitizing paths, usernames and content where necessary.

5. Document the backups and what can be restored. Establish which backups existed before the upgrade and what each contains. Record the database, configuration, data directory and corresponding software version separately. According to the documentation, the built-in updater’s automatic backup does not include the database or data directory. Q4 Do not overwrite an existing backup with an uncertain intermediate state. If components are missing or their timing is unclear, explicitly account for that in the recovery plan.

6. Agree on a limited next step. The status, first exception, installation type and backup inventory provide a basis for deciding what needs to be checked in a separate recovery environment. If there is an explicit permissions error, the responsible database administrator can examine the effective permissions. If a table already exists, its origin and migration state need to be understood. Deleting the table simply because its name appears in the error does not explain the state. Plan any continuation of the upgrade or restoration only after assessing these findings.

How to verify a successful recovery

Verification should cover both the technical state and the functions you actually need. Document the agreed target version and completion of the intended upgrade or recovery procedure. The reported status and actual operation should then agree: the instance no longer requires a database upgrade, is operating normally, and supports the affected task.

Using an authorized test account, check an existing non-sensitive file and a share prepared specifically for testing. If you use synchronization or an Office integration, include an appropriate test. Then review the relevant logs for new errors. Disabling maintenance mode or reaching the login page alone is not sufficient verification after an interrupted database migration.

Frequently asked questions

Can I simply set maintenance to false?

Allowing access does not establish that the migration is complete. For this failure, first investigate the interruption and carry out the appropriate recovery procedure. Then verify normal operation together with the functions you need.

Should I delete the table that already exists?

The message initially tells you that an expected operation encountered an existing name. It does not say that the associated data is disposable. Posts describing table deletion are not a general repair procedure for your instance. Without a precise assessment of its state, essential information for such an intervention is missing.

Can I simply start the old container image?

Nextcloud does not support downgrading an existing installation. For a return to an earlier version, its documentation points to a fresh installation and restoration from backups. Q3 An older application version alone does not establish whether the existing database corresponds to the appropriate point in time. Document any image changes already made so that the next steps start from the actual state.

Is every database schema mismatch warning dangerous?

A schema warning after a successful update needs different treatment from an exception that stops the upgrade. The open overview issue also includes warnings after successful completion. Q6 The full result, current status and specific functional problems matter more than the warning’s heading alone.

Was this problem fixed in Nextcloud 35.0.2?

The sources examined do not support that claim: the original case specifically describes an attempt to upgrade to 35.0.2. A different participant later reports success after making several changes. That confirms neither a generally applicable fix nor a successful outcome for the original reporter. Q1

What information should I provide when asking for help?

The installation type, starting and target versions, time, first exception, current status, actions already taken and the scope of your backups. Also explain which function is unavailable. Do not put a complete config.php, database passwords or backups containing actual file contents into a public request.

Where to get help

The Nextcloud administration documentation is the starting point for status checks and the upgrade procedure appropriate to your installation. Q2 Q3 Specific installation problems are discussed in the Nextcloud help forum. Q1 The project’s issue tracker is appropriate for a software defect that has been narrowed down; read the existing discussion and check what it actually establishes. A report closed as a duplicate is not confirmation that the defect has been fixed. Q5 Q6

Describe your issue

Is your Nextcloud still unreachable after an upgrade, or does it continue to require a database migration? Tell KAN KAI its current state and the last state known to be working. The information from these diagnostic steps helps establish what can be investigated, which backups are needed, and whether the operator or vendor needs to be involved.

Include in your request: private or business use · unavailable function · installation type · versions · first error message · current status · changes already made · available backups. This creates a concrete starting point for a clearly scoped diagnosis or recovery engagement.