Question
Can a failed Bitbucket Server or Data Center upgrade be resumed, or is a full pre-upgrade restore required?
Lax Orbit
0 reputation · 24 Oct 2022, 23:00 UTC
67.3K views
Loading…
0 reputation · 24 Oct 2022, 23:00 UTC
I need to decide the safe recovery path after a Bitbucket upgrade fails before completing the upgrade wizard. The goal is to avoid starting the application against a partially migrated database or mixed-version cluster nodes.
Bitbucket does not automatically roll back a failed upgrade, and database schema changes are not officially reversible. The upgrade log may indicate where the failure occurred, but it is unclear whether the wizard can be safely resumed on the existing BITBUCKET_HOME and database, or whether administrators must always restore the home directory and database dump from a pre-upgrade backup and restart the previous version. This distinction matters for single-node Server instances and multi-node Data Center clusters, where every node must run the same version.
Assumptions: Bitbucket Server or Data Center, a pre-upgrade backup exists, and the failure occurred during the upgrade wizard rather than after startup. Version alignment between binaries, home directory, and database must be confirmed before any restart.
Can the upgrade wizard resume after a failure without restoring from backup? Does resuming risk database schema inconsistency or unsupported mixed-version behavior? When is a full pre-upgrade restore the only supported option?
35275 reputation · 25 Oct 2022, 00:33 UTC
Do not resume the upgrade wizard against the same BITBUCKET_HOME and database after a failed upgrade that has started the new Bitbucket version. Restore the pre-upgrade home directory and database dump, start the previous version, confirm health, then rerun the upgrade. If the failure happened before the new application started—such as an installer, extraction, or license problem—and no schema migration ran, you may fix the precondition and rerun the installer, but this is not a wizard resume.
The upgrade wizard applies schema migration and version updates as one sequence. Bitbucket does not provide an official rollback or resume point for database migrations. A failure can leave a partially migrated schema, mismatched home-directory format, or plugins from the new version. Restarting the new binaries can duplicate or skip migration changes, causing startup errors, repository or index inconsistency, and unsupported mixed-version behavior in Data Center.
Did the new Bitbucket process start successfully, or did any database schema migration run after the failure? If yes, a full pre-upgrade restore is required. If no, only the installer precondition needs fixing before rerunning.
bitbuckettail -n 100 '$BITBUCKET_HOME/log/atlassian-bitbucket.log'
ps -ef | grep bitbucket
ls '$BITBUCKET_HOME'These are read-only checks. Do not copy BITBUCKET_HOME from a running new-version instance back to the old version, and do not restore to a live production cluster without stopping and quiescing nodes first.
A full pre-upgrade restore is required when the new version has started, the wizard reports a database migration failure, logs show incomplete schema changes, or any Data Center node has been started with the new binaries. Because this guidance depends on your exact Bitbucket version, treat it as a draft for human review against the current Atlassian upgrade documentation.
Use comments to ask for clarification. Post a solution as an answer.
5,820 reputation · 25 Oct 2022, 10:34 UTC
A critical detail to consider is that Bitbucket's database migrations are not atomic across the entire upgrade process. Because the application does not support automated rollbacks of schema changes, any failure during the upgrade wizard often leaves the database in a state that is neither the old version nor the new version.
In Data Center environments, this risk is amplified. Attempting to resume or restart without a full restore can lead to a mixed-version state across the cluster, which is unsupported and may cause synchronization failures or data corruption. For a safe recovery, verify the following:
atlassian-plugin.log to identify the specific failed migration task, but treat this as diagnostic data rather than a guide for manual fixes.BITBUCKET_HOME and database dump.