{"record":{"id":"d3ca4297adad93f6","repo":"apache/iceberg","slug":"database-connection-timeout","errorCode":null,"errorMessage":"Database Connection timeout","messagePattern":"Database Connection timeout","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcTableOperations.java","lineNumber":123,"sourceCode":"    String newMetadataLocation = writeNewMetadataIfRequired(newTable, metadata);\n    try {\n      Map<String, String> table =\n          JdbcUtil.loadTable(schemaVersion, connections, catalogName, tableIdentifier);\n\n      if (base != null) {\n        validateMetadataLocation(table, base);\n        String oldMetadataLocation = base.metadataFileLocation();\n        // Start atomic update\n        LOG.debug(\"Committing existing table: {}\", tableName());\n        updateTable(newMetadataLocation, oldMetadataLocation);\n      } else {\n        // table not exists create it\n        LOG.debug(\"Committing new table: {}\", tableName());\n        createTable(newMetadataLocation);\n      }\n\n    } catch (SQLTimeoutException e) {\n      throw new UncheckedSQLException(e, \"Database Connection timeout\");\n    } catch (SQLTransientConnectionException | SQLNonTransientConnectionException e) {\n      throw new UncheckedSQLException(e, \"Database Connection failed\");\n    } catch (DataTruncation e) {\n      throw new UncheckedSQLException(e, \"Database data truncation error\");\n    } catch (SQLWarning e) {\n      throw new UncheckedSQLException(e, \"Database warning\");\n    } catch (SQLException e) {\n      if (JdbcUtil.isConstraintViolation(e)) {\n        if (currentMetadataLocation() == null) {\n          throw new AlreadyExistsException(e, \"Table already exists: %s\", tableIdentifier);\n        } else {\n          throw new UncheckedSQLException(e, \"Table already exists: %s\", tableIdentifier);\n        }\n      }\n\n      throw new UncheckedSQLException(e, \"Unknown failure\");\n    } catch (InterruptedException e) {\n      Thread.currentThread().interrupt();","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcTableOperations.java#L105-L141","documentation":"Thrown when the commit to the JDBC catalog fails with SQLTimeoutException — the database operation (updating the metadata row) timed out, often because a connection could not be obtained within the configured timeout. The commit did not complete, so the table metadata is unchanged.","triggerScenarios":"doCommit() executes UPDATE/INSERT via the pooled connection and the driver throws SQLTimeoutException (login timeout, socket timeout, or lock wait timeout on the metadata row).","commonSituations":"Database overloaded or under heavy lock contention on the table row, slow network to DB, very small connection/login timeout configured in JDBC URL properties, long-running transactions blocking the row.","solutions":["Increase JDBC timeout properties in the URL (e.g. connectTimeout, socketTimeout, loginTimeout) or pool timeouts.","Check for lock contention on the catalog row from other writers; commit is retried by Iceberg so transient timeouts may succeed on retry.","Verify database performance/load at failure time.","Retry the commit — Iceberg's commit retry may resolve transient timeouts."],"exampleFix":"// before\nString uri = \"jdbc:postgresql://db/iceberg?connectTimeout=100\";\n// after\nString uri = \"jdbc:postgresql://db/iceberg?connectTimeout=30000&socketTimeout=60000\";","handlingStrategy":"retry","validationCode":"// check DB responsiveness and lock waits before committing\nlong start = System.nanoTime();\ntry (var conn = java.sql.DriverManager.getConnection(dbUrl, dbProps);\n     var st = conn.createStatement(); var rs = st.executeQuery(\"SELECT 1\")) {\n  long ms = (System.nanoTime() - start) / 1_000_000;\n  if (ms > 5_000) throw new IllegalStateException(\"Catalog DB slow: \" + ms + \"ms\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  table.refresh();\n  table.transaction().commitTransaction();\n} catch (UncheckedSQLException e) {\n  if (e.getCause() instanceof java.sql.SQLTimeoutException) {\n    retryWithBackoff(() -> { /* re-attempt commit */ });\n  } else throw e;\n}","preventionTips":["Configure generous connect/socket timeouts in the JDBC URL.","Monitor row-lock contention on the catalog table.","Retry commits; Iceberg's optimistic retry loop handles transient timeouts."],"tags":["jdbc","timeout","database"],"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"}