'Failed to restore backup: Incompatible version' error during SonarQube major version restore

Direct answer

You cannot restore a SonarQube 9.9 backup directly to a 10.x instance. The “Incompatible version” error enforces major-version equality: the backup’s embedded version must match the target SonarQube major version. The supported path is to restore to the same major version first, then perform an in-place upgrade to 10.x.

Likely explanation versus confirmed facts

Likely explanation: SonarQube’s restore utility reads version metadata inside the backup ZIP and aborts when the major version differs from the running instance. Because 9.9 and 10.x are different major lines, the database migration step is rejected before it runs.

Confirmed facts: SonarQube backups contain a JDBC dump and configuration files only; Elasticsearch indices are excluded and are rebuilt after startup. No built-in backup checksum exists. Backups taken while the source instance is running may capture partial data and cause foreign-key violations during restore. Documented minor-version tolerance for backup restoration is not established; treat major-version equality as strict.

Steps for this case

1. Stop the source SonarQube instance before taking a new backup, or confirm the existing 9.9 backup was taken while the instance was stopped.
2. Provision a temporary SonarQube 9.9.x instance matching the backup’s minor line.
3. Restore the 9.9 backup to that 9.9 instance.
4. Start the 9.9 instance and allow Elasticsearch indices to rebuild.
5. Run the official SonarQube upgrade to 10.x on the same instance. Let the database migration complete before using the instance.
6. Decommission the temporary 9.9 instance only after the 10.x upgrade and verification succeed.

Verification

Elasticsearch indices are not in the backup. Confirm rebuild completion programmatically rather than relying only on web.log:

curl -s http://localhost:9200/_cat/indices?v
curl -s "http://localhost:9200/_cluster/health?wait_for_status=green&timeout=300s"

Look for index status green and cluster health green. If the cluster stays yellow or red, increase Elasticsearch heap and restart the rebuild. Then query the SonarQube database schema-version table and compare it to the 10.x release version; exact table names vary by release, so check your release notes.

Missing diagnostic detail

Is the target 10.x instance a fresh installation, or does it already contain production data that must be preserved? This determines whether an in-place upgrade is safe or whether you need a parallel migration environment.

Draft for review: verify the Elasticsearch port, heap settings, and schema-version table name against your SonarQube 10.x release notes before applying to production.