{"record":{"id":"dbb4dcb84efe93b7","repo":"SonarSource/sonarqube","slug":"unsupported-database-migration-status","errorCode":null,"errorMessage":"UNSUPPORTED_DATABASE_MIGRATION_STATUS","messagePattern":"UNSUPPORTED_DATABASE_MIGRATION_STATUS","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"server/sonar-webserver-webapi-v2/src/main/java/org/sonar/server/v2/api/system/controller/DatabaseMigrationsController.java","lineNumber":71,"sourceCode":"    this.database = database;\n  }\n\n  @Operation(summary = \"Gets the status of ongoing database migrations, if any\", description = \"Return the detailed status of ongoing database migrations\" +\n    \" including starting date. If no migration is ongoing or needed it is still possible to call this endpoint and receive appropriate information.\")\n  @GetMapping\n  public DatabaseMigrationsResponse getStatus() {\n    Optional<Long> currentVersion = databaseVersion.getVersion();\n    checkState(currentVersion.isPresent(), NO_CONNECTION_TO_DB);\n    DatabaseVersion.Status status = databaseVersion.getStatus();\n    if (status == DatabaseVersion.Status.UP_TO_DATE || status == DatabaseVersion.Status.REQUIRES_DOWNGRADE) {\n      return new DatabaseMigrationsResponse(databaseMigrationState);\n    } else if (!database.getDialect().supportsMigration()) {\n      return new DatabaseMigrationsResponse(DatabaseMigrationState.Status.STATUS_NOT_SUPPORTED);\n    } else {\n      return switch (databaseMigrationState.getStatus()) {\n        case RUNNING, FAILED, SUCCEEDED -> new DatabaseMigrationsResponse(databaseMigrationState);\n        case NONE -> new DatabaseMigrationsResponse(DatabaseMigrationState.Status.MIGRATION_REQUIRED);\n        default -> throw new IllegalArgumentException(UNSUPPORTED_DATABASE_MIGRATION_STATUS);\n      };\n    }\n\n  }\n\n  public record DatabaseMigrationsResponse(\n    String status,\n    @Nullable Integer completedSteps,\n    @Nullable Integer totalSteps,\n    @Nullable String startedAt,\n    @Nullable String message,\n    @Nullable String expectedFinishTimestamp) {\n\n    public DatabaseMigrationsResponse(DatabaseMigrationState state) {\n      this(state.getStatus().toString(),\n        state.getCompletedMigrations(),\n        state.getTotalMigrations(),\n        state.getStartedAt().map(d -> d.atZone(ZoneOffset.UTC)).map(DateTimeFormatter.ISO_DATE_TIME::format).orElse(null),","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver-webapi-v2/src/main/java/org/sonar/server/v2/api/system/controller/DatabaseMigrationsController.java#L53-L89","documentation":"IllegalArgumentException thrown by DatabaseMigrationsController.getStatus when databaseMigrationState.getStatus() returns a value not covered by the switch (anything other than RUNNING, FAILED, SUCCEEDED, NONE) on a database whose dialect supports migration. It signals the controller encountered an unknown/legacy migration status enum value.","triggerScenarios":"GET /api/v2/system/database-migrations (or liveness-driven call) while the migration state holds an unmapped status — typically a newly added enum constant not yet handled by this controller, or an unexpected state serialized in the DB.","commonSituations":"Version mismatch between webapp modules after a partial upgrade, custom patching, or a new SonarQube release adding a status constant while an older controller build is running.","solutions":["Upgrade SonarQube so all modules share the same DatabaseMigrationState enum","Check the MIGRATIONS/migration state in the DB for an unexpected status value","Restart the server to reset transient migration state","If upgrade is impossible, report the status value to SonarSource support"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// poll readiness instead of assuming\n// GET /api/v2/system/status until UP before calling database-migrations\n","typeGuard":null,"tryCatchPattern":"try {\n    resp = api.databaseMigrationsStatus();\n} catch (ServerErrorException e) {\n    // unexpected migration status: retry with backoff; upgrade server if persistent\n}","preventionTips":["Apply upgrades atomically (all nodes/modules same version)","Poll /api/v2/system/status before invoking migration-status endpoints","Don't hand-edit migration state in the DB"],"tags":["java","database-migration","enum"],"backgroundTag":"unsupported-enum-value","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}