{"record":{"id":"f3affda9cf568c5d","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-catalog-connection-failed","errorCode":null,"errorMessage":"Cannot initialize JDBC catalog: Connection failed","messagePattern":"Cannot initialize JDBC catalog: Connection failed","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java","lineNumber":224,"sourceCode":"        });\n  }\n\n  private void initializeCatalogTables() {\n    LOG.trace(\"Creating database tables (if missing) to store iceberg catalog\");\n\n    try {\n      atomicCreateTable(\n          JdbcUtil.CATALOG_TABLE_VIEW_NAME,\n          JdbcUtil.V0_CREATE_CATALOG_SQL,\n          \"to store iceberg catalog tables\");\n      atomicCreateTable(\n          JdbcUtil.NAMESPACE_PROPERTIES_TABLE_NAME,\n          JdbcUtil.CREATE_NAMESPACE_PROPERTIES_TABLE_SQL,\n          \"to store iceberg catalog namespace properties\");\n    } catch (SQLTimeoutException e) {\n      throw new UncheckedSQLException(e, \"Cannot initialize JDBC catalog: Query timed out\");\n    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {\n      throw new UncheckedSQLException(e, \"Cannot initialize JDBC catalog: Connection failed\");\n    } catch (SQLException e) {\n      throw new UncheckedSQLException(e, \"Cannot initialize JDBC catalog\");\n    } catch (InterruptedException e) {\n      Thread.currentThread().interrupt();\n      throw new UncheckedInterruptedException(e, \"Interrupted in call to initialize\");\n    }\n  }\n\n  private void updateSchemaIfRequired() {\n    try {\n      connections.run(\n          conn -> {\n            DatabaseMetaData dbMeta = conn.getMetaData();\n            try (ResultSet typeColumn =\n                dbMeta.getColumns(\n                    null, null, JdbcUtil.CATALOG_TABLE_VIEW_NAME, JdbcUtil.RECORD_TYPE)) {\n              if (typeColumn.next()) {\n                LOG.debug(\"{} already supports views\", JdbcUtil.CATALOG_TABLE_VIEW_NAME);","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java#L206-L242","documentation":"JdbcCatalog.initializeCatalogTables wraps SQLTransientConnectionException and SQLNonTransientConnectionException in UncheckedSQLException with \"Cannot initialize JDBC catalog: Connection failed\". It means the JDBC driver could not establish or maintain a connection while setting up the catalog's metadata tables.","triggerScenarios":"Calling JdbcCatalog.initialize(...) when the driver raises SQLTransientConnectionException or SQLNonTransientConnectionException during CREATE TABLE — wrong host/port, DB down, rejected auth at connection level, or pool exhaustion.","commonSituations":"Misconfigured jdbc URI (host, port, database name); database container not started or crashed; firewall/security group blocking the DB port; TLS requirement mismatch; wrong credentials; connection pool limit reached.","solutions":["Verify the JDBC URI (host, port, dbname) and that the database is running and accepting connections.","Check network/firewall/security-group rules between the client and the database.","Validate username/password and auth/TLS configuration (e.g. sslmode for PostgreSQL).","Increase pool size or connection timeout if connections are being exhausted under load.","For transient errors, retry initialization after confirming the DB is healthy."],"exampleFix":"// before\n\"uri\" -> \"jdbc:postgresql://localhost:5432/iceberg\"  // DB on remote host\n\n// after (correct host + TLS)\n\"uri\" -> \"jdbc:postgresql://db.prod.internal:5432/iceberg?ssl=true&sslmode=require\"","handlingStrategy":"retry","validationCode":"// pre-flight connectivity check\ntry (Connection c = DriverManager.getConnection(jdbcUri, user, pass)) {\n  c.createStatement().executeQuery(\"SELECT 1\");\n} catch (SQLException e) {\n  throw new IllegalStateException(\"Cannot reach catalog DB at \" + jdbcUri, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(\"app\", props);\n} catch (UncheckedSQLException e) {\n  if (e.getMessage().contains(\"Connection failed\")) {\n    if (isTransient(e.getCause()) && attempt < maxRetries) { backoffAndRetry(); }\n    else { throw new ConfigurationException(\"JDBC catalog unreachable — check uri/credentials/firewall\", e); }\n  } else { throw e; }\n}","preventionTips":["Validate the JDBC URI, credentials, and TLS settings with a standalone connection test before launching jobs","Ensure DB host/port is reachable from the execution network (firewalls, VPCs, service meshes)","Configure HikariCP/Driver retry and pool sizing so transient drops do not abort initialization","Run retries with exponential backoff for SQLTransientConnectionException causes"],"tags":["jdbc","connection","catalog-init","sql"],"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"}