{"record":{"id":"834a9b853c0d1724","repo":"SonarSource/sonarqube","slug":"the-database-must-be-manually-upgraded-please-bac","errorCode":null,"errorMessage":"The database must be manually upgraded. Please backup the database and browse /setup. For more information: %s","messagePattern":"The database must be manually upgraded\\. Please backup the database and browse /setup\\. For more information: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/sonar-webserver-core/src/main/java/org/sonar/server/platform/DatabaseServerCompatibility.java","lineNumber":67,"sourceCode":"    this.sonarRuntime = sonarRuntime;\n  }\n\n  @Override\n  public void start() {\n    DatabaseVersion.Status status = version.getStatus();\n    if (status == DatabaseVersion.Status.REQUIRES_DOWNGRADE) {\n      throw MessageException.of(\"Database was upgraded to a more recent version of SonarQube. \"\n        + \"A backup must probably be restored or the DB settings are incorrect.\");\n    }\n    if (status == DatabaseVersion.Status.REQUIRES_UPGRADE) {\n      Optional<Long> currentVersion = this.version.getVersion();\n      if (currentVersion.isPresent() && currentVersion.get() < DatabaseVersion.MIN_UPGRADE_VERSION) {\n        throw MessageException.of(buildVersionTooOldMessage());\n      }\n      String documentationLink = documentationLinkGenerator.getDocumentationLink(\"/server-upgrade-and-maintenance/upgrade/roadmap/\");\n      String msg = String.format(\"The database must be manually upgraded. Please backup the database and browse /setup. \"\n        + \"For more information: %s\", documentationLink);\n      LoggerFactory.getLogger(DatabaseServerCompatibility.class).warn(msg);\n      Logger logger = LoggerFactory.getLogger(STARTUP_LOGGER_NAME);\n      logger.warn(HIGHLIGHTER);\n      logger.warn(msg);\n      logger.warn(HIGHLIGHTER);\n    }\n  }\n\n  private String buildVersionTooOldMessage() {\n    if (sonarRuntime.getEdition() == SonarEdition.COMMUNITY) {\n      return \"The version of SonarQube you are trying to upgrade from is too old. Please upgrade to the \" +\n        MIN_UPGRADE_VERSION_COMMUNITY_BUILD_READABLE + \" version first.\";\n    } else {\n      return \"The version of SonarQube you are trying to upgrade from is too old. Please upgrade to the \" +\n        MIN_UPGRADE_VERSION_HUMAN_READABLE + \" Long-Term Active version first.\";\n    }\n\n  }\n","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver-core/src/main/java/org/sonar/server/platform/DatabaseServerCompatibility.java#L49-L85","documentation":"During startup, DatabaseServerCompatibility checks the schema version recorded in the database. When the stored version is below MIN_UPGRADE_VERSION but still requires a manual upgrade path, the server logs (via the class logger and the startup logger, with highlight separators) that the database must be manually upgraded by browsing /setup, including a documentation link. Startup cannot proceed automatically.","triggerScenarios":"Starting a SonarQube server version that is one or more long-term steps ahead of the database schema (e.g. jumping multiple LTS versions), after currentVersion check passes the too-old threshold but the DB schema still predates automatic migration.","commonSituations":"Skipping upgrade steps (direct LTS-to-next-LTS jumps); restoring an old DB dump under a new SonarQube version; Docker image upgraded while the volume holds an old schema.","solutions":["Back up the database, then open http://<server>/setup and follow the guided database upgrade.","Upgrade through intermediate LTS versions if the roadmap link indicates multiple hops.","After /setup completes, restart the SonarQube server.","Keep the old DB backup until the upgraded instance is verified."],"exampleFix":"// before\ndocker run sonarqube:10-new // DB schema from 8.x\n// after\ndocker run sonarqube:9.9-lts && browse /setup  # upgrade stepwise\nthen\ndocker run sonarqube:10-new","handlingStrategy":"fallback","validationCode":"// before starting the server, check the schema version\nlong schemaVersion = readSchemaVersion(db);\nif (schemaVersion < DatabaseVersion.MIN_UPGRADE_VERSION) {\n  throw new IllegalStateException(\"Run /setup upgrade before starting SonarQube \" + targetVersion);\n}","typeGuard":null,"tryCatchPattern":"catch (MessageException e) {\n  // DB too old: halt automation, back up DB, run /setup, then restart\n  backupDatabase();\n  runSetupUpgrade();\n  restartServer();\n}","preventionTips":["Upgrade through documented LTS path; never skip multiple versions.","Always run /setup between binary upgrades.","Back up the database before every upgrade.","Keep Docker volumes and image versions in lockstep."],"tags":["database","upgrade","startup","sonarqube"],"backgroundTag":"incompatible-source-type","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}