SonarSource/sonarqube · critical

Fail to connect to database

Error message

Fail to connect to database

What it means

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.

Source

Thrown at server/sonar-db-migration/src/main/java/org/sonar/db/DefaultDatabase.java:131

  private final Settings settings;
  private ProfiledDataSource datasource;
  private Dialect dialect;
  private Properties properties;

  public DefaultDatabase(LogbackHelper logbackHelper, Settings settings) {
    this.logbackHelper = logbackHelper;
    this.settings = settings;
  }

  @Override
  public void start() {
    initSettings();
    try {
      initDataSource();
      checkConnection();

    } catch (Exception e) {
      throw new IllegalStateException("Fail to connect to database", e);
    }
  }

  @VisibleForTesting
  void initSettings() {
    properties = new Properties();
    completeProperties(settings, properties, SONAR_JDBC);
    completeDefaultProperty(properties, JDBC_URL.getKey(), DEFAULT_URL);
    doCompleteProperties(properties);

    String jdbcUrl = properties.getProperty(JDBC_URL.getKey());
    String dialectId = properties.getProperty(SONAR_JDBC_DIALECT);
    dialect = (StringUtils.isNotBlank(dialectId) ? DialectUtils.findById(dialectId) : DialectUtils.findByJdbcUrl(jdbcUrl))
      .orElseThrow(() -> MessageException.of(
        "Unable to determine database dialect to use within sonar with dialect " + dialectId + " jdbc url " + jdbcUrl));
    properties.setProperty(SONAR_JDBC_DRIVER, dialect.getDefaultDriverClassName());
  }

View on GitHub (pinned to 184c821202)

Solutions

1. Read the 'Caused by' exception below this message in logs — it names the actual cause (UnknownHost, Connection refused, Access denied, driver class not found).
2. 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').
3. Confirm the JDBC driver jar is present in SONARQUBE_HOME/extensions/jdbc-drivers and matches the DB version.
4. Ensure the database server is running and accepts connections (check DB service status, docker compose, network/firewall rules).

Example fix

// before (sonar.properties)
# sonar.jdbc.url=jdbc:postgresql://localhost:5432/sonarqube

// after — uncommented and verified
sonar.jdbc.url=jdbc:postgresql://db.internal:5432/sonarqube
sonar.jdbc.username=sonar
sonar.jdbc.password=secret

// pre-startup check script
nc -zv "$DB_HOST" "$DB_PORT" || echo "DB unreachable"
ls "$SONARQUBE_HOME/extensions/jdbc-drivers" | grep -i postgres

try {
  database.start();
} catch (IllegalStateException e) {
  LOGGER.error("DB bootstrap failed; inspect root cause", e.getCause());
  throw e;
}

When it happens

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

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

Related errors

• Can not connect to database. Please check connectivity and s
• Unsupported JDBC driver provider: %s
• The database must be manually upgraded. Please backup the da
• Analysis report %s part %s is missing in database
• Analysis Export failed after processing %d analyses successf

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