{"record":{"id":"341a082bf9c1c0d7","repo":"apache/iceberg","slug":"failed-to-connect-s","errorCode":null,"errorMessage":"Failed to connect: %s","messagePattern":"Failed to connect: (.+?)","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcClientPool.java","lineNumber":90,"sourceCode":"    retryableStatusCodes.addAll(COMMON_RETRYABLE_CONNECTION_SQL_STATES);\n    String configuredRetryableStatuses = props.get(JdbcUtil.RETRYABLE_STATUS_CODES);\n    if (configuredRetryableStatuses != null) {\n      retryableStatusCodes.addAll(\n          Arrays.stream(configuredRetryableStatuses.split(\",\"))\n              .map(status -> status.replaceAll(\"\\\\s+\", \"\"))\n              .collect(Collectors.toSet()));\n    }\n\n    this.dbUrl = dbUrl;\n  }\n\n  @Override\n  protected Connection newClient() {\n    try {\n      Properties dbProps = JdbcUtil.filterAndRemovePrefix(properties, JdbcCatalog.PROPERTY_PREFIX);\n      return DriverManager.getConnection(dbUrl, dbProps);\n    } catch (SQLException e) {\n      throw new UncheckedSQLException(e, \"Failed to connect: %s\", dbUrl);\n    }\n  }\n\n  @Override\n  protected Connection reconnect(Connection client) {\n    close(client);\n    return newClient();\n  }\n\n  @Override\n  protected void close(Connection client) {\n    try {\n      client.close();\n    } catch (SQLException e) {\n      throw new UncheckedSQLException(e, \"Failed to close connection\");\n    }\n  }\n","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcClientPool.java#L72-L108","documentation":"Thrown when the JDBC catalog's connection pool cannot open a new JDBC connection to the backing database. DriverManager.getConnection is wrapped so any SQLException becomes an UncheckedSQLException carrying the database URL. It indicates the catalog cannot reach or authenticate against its metadata store.","triggerScenarios":"JdbcClientPool.newClient() fails when DriverManager.getConnection(dbUrl, dbProps) throws SQLException, typically on pool cold start or after all pooled connections were invalidated during reconnect.","commonSituations":"Wrong JDBC URL or hostname, database down or unreachable (network/firewall), bad credentials in catalog properties, missing JDBC driver on classpath, SSL misconfiguration, connection limit exhausted on the DB server.","solutions":["Verify the URI catalog property points to a reachable database (test with a plain JDBC client or ping).","Confirm the JDBC driver jar is on the runtime classpath for the configured URL scheme.","Check username/password and any ssl properties passed via catalog properties are correct.","Confirm the database server is running and accepting connections (connection limits, firewall).","Increase DriverManager login timeout or pool init settings if timeouts are the cause."],"exampleFix":"// before\nMap<String, String> props = Map.of(\"uri\", \"jdbc:postgresql://wrong-host:5432/iceberg\");\nJdbcCatalog catalog = new JdbcCatalog();\ncatalog.setConf(conf); catalog.initialize(\"jdbc\", props);\n// after\nMap<String, String> props = Map.of(\n  \"uri\", \"jdbc:postgresql://db-host:5432/iceberg\",\n  \"jdbc.user\", \"iceberg\",\n  \"jdbc.password\", \"secret\",\n  \"driver\", \"org.postgresql.Driver\");","handlingStrategy":"try-catch","validationCode":"// verify connectivity before initializing the catalog\ntry (var conn = java.sql.DriverManager.getConnection(dbUrl, dbProps)) {\n  // connection OK\n} catch (java.sql.SQLException e) {\n  throw new IllegalStateException(\"Catalog DB unreachable: \" + e.getMessage(), e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(\"jdbc\", props);\n} catch (UncheckedSQLException e) {\n  if (e.getCause() instanceof java.sql.SQLException sql && \"08001\".equals(sql.getSQLState())) {\n    // handle unreachable DB: alert / retry with backoff\n  }\n  throw e;\n}","preventionTips":["Test the JDBC URL and credentials with a simple client before configuring the catalog.","Keep the JDBC driver jar on the classpath matching the DB version.","Set explicit connect/login timeouts and verify network/firewall paths.","Store credentials via a secrets mechanism, not plaintext properties files."],"tags":["jdbc","network","database","connection"],"backgroundTag":"connection-refused","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}