Can not connect to database. Please check connectivity and s

Error message

Can not connect to database. Please check connectivity and settings (see the properties prefixed by 'sonar.jdbc.').

What it means

checkConnection is the connectivity probe inside DefaultDatabase.start: it obtains a java.sql.Connection from the datasource and initializes the dialect from database metadata. An SQLException here means the datasource was built but no actual connection could be obtained, and it is rethrown as this IllegalStateException pointing the user at the sonar.jdbc.* properties.

Source

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

    enableSqlLogging(datasource, logbackHelper.getLoggerLevel("sql") == Level.TRACE);
  }

  private HikariDataSource createHikariDataSource() {
    HikariConfig config = new HikariConfig(extractCommonsHikariProperties(properties));
    if (!dialect.getConnectionInitStatements().isEmpty()) {
      config.setConnectionInitSql(dialect.getConnectionInitStatements().get(0));
    }
    config.setConnectionTestQuery(dialect.getValidationQuery());
    return new HikariDataSource(config);
  }

  private void checkConnection() {
    Connection connection = null;
    try {
      connection = datasource.getConnection();
      dialect.init(connection.getMetaData());
    } catch (SQLException e) {
      throw new IllegalStateException("Can not connect to database. Please check connectivity and settings (see the properties prefixed by 'sonar.jdbc.').", e);
    } finally {
      DatabaseUtils.closeQuietly(connection);
    }
  }

  @Override
  public void stop() {
    if (datasource != null) {
      datasource.close();
    }
  }

  @Override
  public final Dialect getDialect() {
    return dialect;
  }

  @Override

View on GitHub (pinned to 184c821202)

Solutions

Check the underlying SQLException cause in the stack trace to distinguish refused-connection vs authentication vs SSL errors.
Review every sonar.jdbc.* property in sonar.properties (url, username, password, driver settings) — the message explicitly points there.
Test the exact JDBC URL from the server machine with a standalone connection (e.g. 'psql -h host -p 5432 -U sonar' or a small JDBC test) to isolate network vs config.
Fix server-side access rules: pg_hba.conf/listen_addresses for PostgreSQL, enable TCP/IP for SQL Server, open the firewall port.
Add required JDBC options to the URL (e.g. sslmode=require for PostgreSQL, encrypt=true for SQL Server) if the DB mandates TLS.

Example fix

// before
sonar.jdbc.url=jdbc:postgresql://db.internal/sonarqube

// after — explicit port and ssl mode
sonar.jdbc.url=jdbc:postgresql://db.internal:5432/sonarqube?sslmode=require

Defensive patterns

Strategy: retry

Validate before calling

// verify connectivity from the server host before startup
psql "postgresql://$USER:$PASS@$DB_HOST:$DB_PORT/$DB" -c 'select 1' || echo 'check sonar.jdbc.* settings'

Try / catch

try {
  checkConnection();
} catch (IllegalStateException e) {
  // inspect SQLException cause: refused vs auth vs ssl, then fix sonar.jdbc.* and restart
}

Prevention

Include explicit port and required TLS options in sonar.jdbc.url.
Align server-side access rules (pg_hba.conf, SQL Server TCP/IP) with the app host.
Monitor DB availability with health checks so outages are caught before startup.
Rotate credentials via secrets management to avoid stale passwords.

When it happens

Trigger: datasource.getConnection() throws SQLException (DB unreachable, auth rejected, TLS/SSL mismatch) or dialect.init fails on metadata while starting the server.

Common situations: Database listening on a different host/port than configured; wrong password or locked account; DB not accepting TCP connections (listen_addresses, pg_hba.conf, SQL Server TCP/IP protocol disabled); SSL requiring encryption while the JDBC URL does not enable it.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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