The database must be manually upgraded. Please backup the da

Error message

The database must be manually upgraded. Please backup the database and browse /setup. For more information: %s

What it means

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.

Source

Thrown at server/sonar-webserver-core/src/main/java/org/sonar/server/platform/DatabaseServerCompatibility.java:67

    this.sonarRuntime = sonarRuntime;
  }

  @Override
  public void start() {
    DatabaseVersion.Status status = version.getStatus();
    if (status == DatabaseVersion.Status.REQUIRES_DOWNGRADE) {
      throw MessageException.of("Database was upgraded to a more recent version of SonarQube. "
        + "A backup must probably be restored or the DB settings are incorrect.");
    }
    if (status == DatabaseVersion.Status.REQUIRES_UPGRADE) {
      Optional<Long> currentVersion = this.version.getVersion();
      if (currentVersion.isPresent() && currentVersion.get() < DatabaseVersion.MIN_UPGRADE_VERSION) {
        throw MessageException.of(buildVersionTooOldMessage());
      }
      String documentationLink = documentationLinkGenerator.getDocumentationLink("/server-upgrade-and-maintenance/upgrade/roadmap/");
      String msg = String.format("The database must be manually upgraded. Please backup the database and browse /setup. "
        + "For more information: %s", documentationLink);
      LoggerFactory.getLogger(DatabaseServerCompatibility.class).warn(msg);
      Logger logger = LoggerFactory.getLogger(STARTUP_LOGGER_NAME);
      logger.warn(HIGHLIGHTER);
      logger.warn(msg);
      logger.warn(HIGHLIGHTER);
    }
  }

  private String buildVersionTooOldMessage() {
    if (sonarRuntime.getEdition() == SonarEdition.COMMUNITY) {
      return "The version of SonarQube you are trying to upgrade from is too old. Please upgrade to the " +
        MIN_UPGRADE_VERSION_COMMUNITY_BUILD_READABLE + " version first.";
    } else {
      return "The version of SonarQube you are trying to upgrade from is too old. Please upgrade to the " +
        MIN_UPGRADE_VERSION_HUMAN_READABLE + " Long-Term Active version first.";
    }

  }

View on GitHub (pinned to 184c821202)

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.

Example fix

// before
docker run sonarqube:10-new // DB schema from 8.x
// after
docker run sonarqube:9.9-lts && browse /setup  # upgrade stepwise
then
docker run sonarqube:10-new

Defensive patterns

Strategy: fallback

Validate before calling

// before starting the server, check the schema version
long schemaVersion = readSchemaVersion(db);
if (schemaVersion < DatabaseVersion.MIN_UPGRADE_VERSION) {
  throw new IllegalStateException("Run /setup upgrade before starting SonarQube " + targetVersion);
}

Try / catch

catch (MessageException e) {
  // DB too old: halt automation, back up DB, run /setup, then restart
  backupDatabase();
  runSetupUpgrade();
  restartServer();
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/834a9b853c0d1724. Report an issue: GitHub.