{"record":{"id":"8d8556551b000941","repo":"SonarSource/sonarqube","slug":"fail-to-connect-to-database","errorCode":null,"errorMessage":"Fail to connect to database","messagePattern":"Fail to connect to database","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/sonar-db-migration/src/main/java/org/sonar/db/DefaultDatabase.java","lineNumber":131,"sourceCode":"  private final Settings settings;\n  private ProfiledDataSource datasource;\n  private Dialect dialect;\n  private Properties properties;\n\n  public DefaultDatabase(LogbackHelper logbackHelper, Settings settings) {\n    this.logbackHelper = logbackHelper;\n    this.settings = settings;\n  }\n\n  @Override\n  public void start() {\n    initSettings();\n    try {\n      initDataSource();\n      checkConnection();\n\n    } catch (Exception e) {\n      throw new IllegalStateException(\"Fail to connect to database\", e);\n    }\n  }\n\n  @VisibleForTesting\n  void initSettings() {\n    properties = new Properties();\n    completeProperties(settings, properties, SONAR_JDBC);\n    completeDefaultProperty(properties, JDBC_URL.getKey(), DEFAULT_URL);\n    doCompleteProperties(properties);\n\n    String jdbcUrl = properties.getProperty(JDBC_URL.getKey());\n    String dialectId = properties.getProperty(SONAR_JDBC_DIALECT);\n    dialect = (StringUtils.isNotBlank(dialectId) ? DialectUtils.findById(dialectId) : DialectUtils.findByJdbcUrl(jdbcUrl))\n      .orElseThrow(() -> MessageException.of(\n        \"Unable to determine database dialect to use within sonar with dialect \" + dialectId + \" jdbc url \" + jdbcUrl));\n    properties.setProperty(SONAR_JDBC_DRIVER, dialect.getDefaultDriverClassName());\n  }\n","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-db-migration/src/main/java/org/sonar/db/DefaultDatabase.java#L113-L149","documentation":"DefaultDatabase.start initializes JDBC settings, creates the data source, and calls checkConnection. Any exception during those steps (driver missing, bad URL, unreachable server, connection failure) is wrapped in this IllegalStateException 'Fail to connect to database'. It is the generic bootstrap failure when the SonarQube server cannot establish a database connection at startup.","triggerScenarios":"Calling start() during platform bootstrap when initDataSource() throws (bad sonar.jdbc.url, missing driver) or checkConnection() throws SQLException because the DB is unreachable or credentials are wrong.","commonSituations":"Wrong sonar.jdbc.url/host/port; database server down or restarting; wrong sonar.jdbc.username/password; JDBC driver jar not in the extensions/jdbc-drivers directory; firewall or Docker networking blocking the DB port.","solutions":["Read the 'Caused by' exception below this message in logs — it names the actual cause (UnknownHost, Connection refused, Access denied, driver class not found).","Verify sonar.jdbc.url, sonar.jdbc.username and sonar.jdbc.password in sonar.properties and test connectivity from the server host (e.g. psql/psql client or 'telnet host 5432').","Confirm the JDBC driver jar is present in SONARQUBE_HOME/extensions/jdbc-drivers and matches the DB version.","Ensure the database server is running and accepts connections (check DB service status, docker compose, network/firewall rules)."],"exampleFix":"// before (sonar.properties)\n# sonar.jdbc.url=jdbc:postgresql://localhost:5432/sonarqube\n\n// after — uncommented and verified\nsonar.jdbc.url=jdbc:postgresql://db.internal:5432/sonarqube\nsonar.jdbc.username=sonar\nsonar.jdbc.password=secret","handlingStrategy":"validation","validationCode":"// pre-startup check script\nnc -zv \"$DB_HOST\" \"$DB_PORT\" || echo \"DB unreachable\"\nls \"$SONARQUBE_HOME/extensions/jdbc-drivers\" | grep -i postgres","typeGuard":null,"tryCatchPattern":"try {\n  database.start();\n} catch (IllegalStateException e) {\n  LOGGER.error(\"DB bootstrap failed; inspect root cause\", e.getCause());\n  throw e;\n}","preventionTips":["Validate sonar.jdbc.url/credentials with a standalone connection test before server startup.","Keep the correct JDBC driver jar in extensions/jdbc-drivers for your DB version.","Add a readiness probe (e.g. docker-compose healthcheck) on the DB before starting SonarQube.","Always read the 'Caused by' chain to identify the real failure."],"tags":["database","startup","jdbc","sonarqube","connectivity"],"backgroundTag":"database-connection-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"}