{"record":{"id":"d6c380ef4319be6e","repo":"apache/iceberg","slug":"database-connection-failed","errorCode":null,"errorMessage":"Database Connection failed","messagePattern":"Database Connection failed","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcTableOperations.java","lineNumber":125,"sourceCode":"      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();\n      throw new UncheckedInterruptedException(e, \"Interrupted during commit\");\n    }","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcTableOperations.java#L107-L143","documentation":"Thrown when doCommit fails with SQLTransientConnectionException or SQLNonTransientConnectionException — the database connection failed during the commit. Transient means a retry might succeed; non-transient means a persistent connection problem. The commit did not land.","triggerScenarios":"doCommit() throws SQLTransientConnectionException or SQLNonTransientConnectionException while executing catalog UPDATE/INSERT — pooled connection lost or cannot be established at commit time.","commonSituations":"Database restart/failover mid-commit, network blip, pool exhausted and connection acquisition failing, DB max_connections reached, authentication expiry.","solutions":["Retry the commit — Iceberg retries commits and transient connection errors often resolve.","Check database availability, max_connections, and pool sizing.","Increase pool size / connection timeout properties so commits don't starve.","Inspect server logs for failover or crash events coinciding with the commit."],"exampleFix":"// before\nMap<String,String> props = Map.of(\"uri\", url); // default pool, exhausted under load\n// after\nMap<String,String> props = Map.of(\"uri\", url, \"pool.maxSize\", \"20\", \"jdbc.max-connections\", \"20\");","handlingStrategy":"retry","validationCode":"// confirm DB reachable and pool not exhausted before batch commits\ntry (var conn = java.sql.DriverManager.getConnection(dbUrl, dbProps)) {\n  if (!conn.isValid(5)) throw new IllegalStateException(\"Catalog DB connection invalid\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  commit();\n} catch (UncheckedSQLException e) {\n  Throwable c = e.getCause();\n  if (c instanceof java.sql.SQLTransientConnectionException) {\n    retryWithBackoff(this::commit); // transient: safe to retry\n  } else throw e;\n}","preventionTips":["Right-size the connection pool for concurrent writers.","Monitor max_connections and failover events on the DB.","Retry transient connection failures with exponential backoff."],"tags":["jdbc","connection","database"],"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"}