{"record":{"id":"be0130e9da450a5e","repo":"apache/iceberg","slug":"cannot-update-jdbc-catalog-query-timed-out","errorCode":null,"errorMessage":"Cannot update JDBC catalog: Query timed out","messagePattern":"Cannot update 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":263,"sourceCode":"              } else {\n                if (PropertyUtil.propertyAsString(\n                        catalogProperties,\n                        JdbcUtil.SCHEMA_VERSION_PROPERTY,\n                        JdbcUtil.SchemaVersion.V0.name())\n                    .equalsIgnoreCase(JdbcUtil.SchemaVersion.V1.name())) {\n                  LOG.debug(\n                      \"{} is being updated to support views\", JdbcUtil.CATALOG_TABLE_VIEW_NAME);\n                  schemaVersion = JdbcUtil.SchemaVersion.V1;\n                  return executeV1CatalogUpdate(conn);\n                } else {\n                  LOG.warn(VIEW_WARNING_LOG_MESSAGE);\n                  return true;\n                }\n              }\n            }\n          });\n    } catch (SQLTimeoutException e) {\n      throw new UncheckedSQLException(e, \"Cannot update JDBC catalog: Query timed out\");\n    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {\n      throw new UncheckedSQLException(e, \"Cannot update JDBC catalog: Connection failed\");\n    } catch (SQLException e) {\n      throw new UncheckedSQLException(e, \"Cannot check and eventually update SQL schema\");\n    } catch (InterruptedException e) {\n      Thread.currentThread().interrupt();\n      throw new UncheckedInterruptedException(e, \"Interrupted in call to initialize\");\n    }\n  }\n\n  private static boolean executeV1CatalogUpdate(Connection conn) throws SQLException {\n    try (PreparedStatement stmt = conn.prepareStatement(JdbcUtil.V1_UPDATE_CATALOG_SQL)) {\n      return stmt.execute();\n    }\n  }\n\n  @Override\n  protected TableOperations newTableOps(TableIdentifier tableIdentifier) {","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java#L245-L281","documentation":"Thrown by JdbcCatalog.updateSchemaIfRequired when the schema-migration check/update query times out (SQLTimeoutException). The catalog verifies and optionally upgrades the catalog tables' schema (e.g. V0 to V1 for view support) during initialize(), and this failure means that round trip exceeded the configured JDBC timeout.","triggerScenarios":"Calling initialize() (via CatalogUtil.loadCatalog) when the database is heavily loaded or the connection's queryTimeout is too small, so the schema check (or V0→V1 migration) statement exceeds the driver's timeout.","commonSituations":"Large iceberg_catalog tables making migration statements slow, network congestion between app and database, or very low connection pool / driver query timeout settings.","solutions":["Increase the JDBC query timeout (driver URL parameters or pool settings, e.g. socketTimeout/queryTimeout)","Check database load and slow-query logs; add indexes on the catalog tables if migration scans are slow","Retry initialization once load subsides","Upgrade the database/host resources if the catalog table has grown very large"],"exampleFix":"// before\nprops.put(\"uri\", \"jdbc:postgresql://db:5432/iceberg\"); // default short timeouts\n// after\nprops.put(\"uri\", \"jdbc:postgresql://db:5432/iceberg?options=-c%20statement_timeout=300000\");","handlingStrategy":"retry","validationCode":"// check configured JDBC timeouts before init\nString uri = props.getProperty(\"uri\");\nif (uri != null && !uri.contains(\"timeout\")) {\n  props.put(\"uri\", uri + \"?options=-c%20statement_timeout=300000\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(name);\n} catch (UncheckedSQLException e) {\n  if (e.getMessage().contains(\"timed out\")) {\n    retryWithBackoff(3); // increase timeout between attempts\n  } else { throw e; }\n}","preventionTips":["Set generous query/socket timeouts on the JDBC URI or connection pool","Monitor DB slow-query log; index large iceberg_catalog tables","Run the V0→V1 migration offline once rather than at every startup","Keep the catalog database near the compute cluster to reduce latency"],"tags":["jdbc","database","timeout","schema-migration"],"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"}