{"record":{"id":"1b4f7ab1a91be7b9","repo":"apache/iceberg","slug":"unknown-failure","errorCode":null,"errorMessage":"Unknown failure","messagePattern":"Unknown failure","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcTableOperations.java","lineNumber":139,"sourceCode":"\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    }\n  }\n\n  private void updateTable(String newMetadataLocation, String oldMetadataLocation)\n      throws SQLException, InterruptedException {\n    int updatedRecords =\n        JdbcUtil.updateTable(\n            schemaVersion,\n            connections,\n            catalogName,\n            tableIdentifier,\n            newMetadataLocation,\n            oldMetadataLocation);\n\n    if (updatedRecords == 1) {","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcTableOperations.java#L121-L157","documentation":"A generic fallback in JdbcTableOperations.doCommit: any SQLException that is not a timeout, connection failure, data truncation, SQLWarning, or unique-constraint violation is wrapped in UncheckedSQLException with the uninformative message 'Unknown failure'. It means the underlying JDBC driver reported an error the catalog did not classify; the root cause is in the chained SQLException.","triggerScenarios":"Any SQL error during loadTable/updateTable/insert that falls outside the caught categories: syntax errors, missing jdbc_tables catalog table, permissions denied, deadlock victims, disk-full on the metadata DB, driver-specific error codes not matching isConstraintViolation.","commonSituations":"Catalog database not initialized (missing jdbc_tables/jdbc_namespaces tables after upgrading or pointing at a fresh DB); DB user lacking INSERT/UPDATE grants; Postgres/MySQL deadlock under concurrent commits; unsupported SQL dialect.","solutions":["Inspect the chained cause: getCause().getSQLException() / print the full stack to see the real SQL error and vendor code","Initialize the JDBC catalog schema (tables jdbc_tables, jdbc_namespaces, etc.) in the target database","Grant the catalog DB user SELECT/INSERT/UPDATE on the catalog tables","If deadlocks are the cause, retry the commit (CommitState/RetryUtil) or reduce commit concurrency"],"exampleFix":"// before\n} catch (UncheckedSQLException e) {\n  LOG.error(\"commit failed\");\n}\n// after\n} catch (UncheckedSQLException e) {\n  LOG.error(\"commit failed\", e.getCause()); // chained SQLException reveals real vendor error\n}","handlingStrategy":"try-catch","validationCode":"// verify catalog DB is initialized and reachable before committing\nassert catalog.tableExists(identifier) || catalog.namespaceExists(identifier.namespace());","typeGuard":null,"tryCatchPattern":"try { commit(); } catch (UncheckedSQLException e) { SQLException sql = (SQLException) e.getCause(); LOG.error(\"SQL state={} vendorCode={}\", sql.getSQLState(), sql.getErrorCode(), sql); }","preventionTips":["Always log the chained cause (SQLState + vendor code), never the wrapper message alone","Initialize jdbc_tables/jdbc_namespaces DDL before first use","Grant the DB user full DML on catalog tables","Enable driver-level logging when diagnosing 'Unknown failure'"],"tags":["jdbc","sql","unclassified-error","catalog-commit"],"backgroundTag":"sql-query-failed","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"}