{"record":{"id":"38eea881c35b630c","repo":"apache/iceberg","slug":"cannot-initialize-jdbc-catalog-query-timed-out","errorCode":null,"errorMessage":"Cannot initialize JDBC catalog: Query timed out","messagePattern":"Cannot initialize JDBC catalog: Query timed out","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java","lineNumber":222,"sourceCode":"            throw e;\n          }\n        });\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)) {","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java#L204-L240","documentation":"JdbcCatalog.initializeCatalogTables creates the iceberg_tables and iceberg_namespace_properties tables at startup, with a configured login/connection timeout. When a JDBC statement fails with SQLTimeoutException (the query exceeded the driver timeout), the catalog wraps it in UncheckedSQLException with \"Cannot initialize JDBC catalog: Query timed out\".","triggerScenarios":"Calling JdbcCatalog.initialize(...) against a database whose CREATE TABLE (or initial connection) exceeds the configured connection/login timeout, producing SQLTimeoutException during atomicCreateTable.","commonSituations":"Database under heavy load or long lock contention; network latency to a remote DB; pool connection validation timeouts (e.g. HikariCP connectionTimeout too low); DB paused/slow to wake (serverless databases).","solutions":["Verify the database is reachable and not paused; wake/resume the serverless instance.","Increase the JDBC timeout settings (e.g. jdbc.loginTimeout / HikariCP connectionTimeout) in the catalog properties.","Check the database for lock contention or long-running transactions blocking DDL.","Test connectivity with the same JDBC URL/credentials outside the app to isolate network issues.","Confirm the schema exists and the user has CREATE privileges so DDL does not stall."],"exampleFix":"// before\nMap<String, String> props = Map.of(\n  JdbcCatalog.PROPERTY_PREFIX + \"user\", \"iceberg\",\n  JdbcCatalog.PROPERTY_PREFIX + \"password\", \"pass\",\n  CatalogProperties.URI, \"jdbc:postgresql://db:5432/iceberg\");\n\n// after (raise timeout so slow startup succeeds)\nMap<String, String> props = Map.of(\n  JdbcCatalog.PROPERTY_PREFIX + \"user\", \"iceberg\",\n  JdbcCatalog.PROPERTY_PREFIX + \"password\", \"pass\",\n  JdbcCatalog.PROPERTY_PREFIX + \"connectionTimeout\", \"30000\",\n  CatalogProperties.URI, \"jdbc:postgresql://db:5432/iceberg\");","handlingStrategy":"retry","validationCode":"// probe the catalog DB before initializing\ntry (Connection c = DriverManager.getConnection(jdbcUri, user, pass)) {\n  c.createStatement().executeQuery(\"SELECT 1\"); // surfaces slow/unreachable DB early\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(\"app\", props);\n} catch (UncheckedSQLException e) {\n  if (e.getMessage().contains(\"Query timed out\")) {\n    // raise connection timeout / wake serverless DB, then retry\n  } else {\n    throw e;\n  }\n}","preventionTips":["Set generous JDBC login/connection timeouts in catalog properties (e.g. iceberg.jdbc.connectionTimeout)","Pre-provision the catalog database and grant CREATE privileges so startup DDL is instant","Monitor DB lock contention; serverless DBs should be pre-warmed before job start"],"tags":["jdbc","timeout","catalog-init","sql"],"backgroundTag":"request-timeout","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"}