{"record":{"id":"8205406562bb2e55","repo":"SonarSource/sonarqube","slug":"failed-to-create-table-schema-migrations","errorCode":null,"errorMessage":"Failed to create table schema_migrations","messagePattern":"Failed to create table schema_migrations","errorType":"exception","errorClass":"java.lang.IllegalStateException","httpStatus":null,"severity":"critical","filePath":"server/sonar-db-migration/src/main/java/org/sonar/server/platform/db/migration/history/MigrationHistoryTableImpl.java","lineNumber":48,"sourceCode":"import org.sonar.server.platform.db.migration.sql.CreateTableBuilder;\n\npublic class MigrationHistoryTableImpl implements MigrationHistoryTable {\n  private static final String VERSION_COLUMN_NAME = \"version\";\n\n  private final Database database;\n\n  public MigrationHistoryTableImpl(Database database) {\n    this.database = database;\n  }\n\n  @Override\n  public void start() {\n    try (Connection connection = createDdlConnection(database)) {\n      if (!DatabaseUtils.tableExists(NAME, connection)) {\n        createTable(connection);\n      }\n    } catch (SQLException e) {\n      throw new IllegalStateException(\"Failed to create table \" + NAME, e);\n    }\n  }\n\n  private void createTable(Connection connection) throws SQLException {\n    List<String> sqls = new CreateTableBuilder(database.getDialect(), NAME)\n      .addColumn(VarcharColumnDef.newVarcharColumnDefBuilder().setColumnName(VERSION_COLUMN_NAME).setIsNullable(false).setLimit(255).build())\n      .build();\n\n    LoggerFactory.getLogger(MigrationHistoryTableImpl.class).info(\"Creating table \" + NAME);\n    for (String sql : sqls) {\n      execute(connection, sql);\n    }\n  }\n\n  private static Connection createDdlConnection(Database database) throws SQLException {\n    Connection res = database.getDataSource().getConnection();\n    res.setAutoCommit(false);\n    return res;","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-db-migration/src/main/java/org/sonar/server/platform/db/migration/history/MigrationHistoryTableImpl.java#L30-L66","documentation":"Thrown by MigrationHistoryTableImpl.start() when creating the sonar-core-schema_migrations table fails with a SQLException. This table tracks which DB migrations have been applied; without it SonarQube cannot boot its database schema layer. The IllegalStateException wraps the underlying SQLException as the cause.","triggerScenarios":"Calling start() when the database is unreachable, credentials are wrong, the configured user lacks CREATE TABLE privileges, or the schema/catalog does not exist.","commonSituations":"First startup against a fresh database with wrong JDBC settings; a DBA restricted the sonar user's DDL rights; network/firewall drops the JDBC connection; unsupported DB version or dialect.","solutions":["Check the root SQLException cause in logs for the actual JDBC error (access denied, unknown database, connection refused).","Verify sonar.jdbc.url/username/password point to an existing, reachable database.","Grant the database user CREATE TABLE privileges on the target schema.","Test connectivity to the DB host/port and retry startup."],"exampleFix":"// before\nsonar.jdbc.url=jdbc:postgresql://localhost:5432/wrongdb\n// after\nsonar.jdbc.url=jdbc:postgresql://localhost:5432/sonar","handlingStrategy":"try-catch","validationCode":"try (Connection c = DriverManager.getConnection(url, user, pass)) { DatabaseMetaData md = c.getMetaData(); } catch (SQLException e) { /* fail fast before migration */ }","typeGuard":null,"tryCatchPattern":"try { historyTable.start(); } catch (IllegalStateException e) { logger.error(\"Migration history table creation failed; check DB connectivity/privileges\", e.getCause()); throw e; }","preventionTips":["Validate JDBC URL/credentials with a smoke connection before starting migrations","Grant DDL (CREATE TABLE) rights to the migration user","Keep the DB reachable and monitor network/firewall rules","Check the root cause (e.getCause()) rather than the wrapper message"],"tags":["database","migration","startup","sql"],"backgroundTag":"database-write-failed","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}