{"record":{"id":"1aa3f5ea8cca263e","repo":"apache/iceberg","slug":"unknown-failure-1aa3f5","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/JdbcViewOperations.java","lineNumber":131,"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, \"View already exists: %s\", viewIdentifier);\n        } else {\n          throw new UncheckedSQLException(e, \"View already exists: %s\", viewIdentifier);\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  @Override\n  protected String viewName() {\n    return viewIdentifier.toString();\n  }\n\n  @Override\n  protected FileIO io() {\n    return fileIO;\n  }\n\n  private void validateMetadataLocation(Map<String, String> view, ViewMetadata base) {\n    String catalogMetadataLocation = view.get(JdbcTableOperations.METADATA_LOCATION_PROP);","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcViewOperations.java#L113-L149","documentation":"JdbcViewOperations.doCommit wraps any SQLException that is not a timeout, connection failure, data truncation, warning, or constraint violation into an UncheckedSQLException with the generic message 'Unknown failure'. This is the catch-all for unexpected database errors during a JDBC catalog view commit, preserving the underlying SQLException as the cause.","triggerScenarios":"Committing a view through a JDBC catalog when the database raises an unexpected SQLException — e.g. schema mismatch in the iceberg_views table, table missing (SQLSyntaxErrorException), lock wait timeout, permission denied on UPDATE/INSERT, or connection dropped mid-statement with an unmapped SQLState.","commonSituations":"Deploying against a JDBC catalog whose backing database schema was created by an older Iceberg version (missing view columns); DB user lacking DML privileges on catalog tables; network interruption between driver and database; DB-specific errors like MySQL 'Lock wait timeout exceeded' or Postgres 'relation does not exist'.","solutions":["Read the wrapped SQLException cause (e.getCause()) to identify the real database error; the message itself is intentionally generic","Verify the JDBC catalog database schema matches the Iceberg version (iceberg_views/iceberg_tables tables and columns exist)","Check the DB user has SELECT/INSERT/UPDATE privileges on the catalog tables","Test basic connectivity and query the catalog tables directly with the same JDBC URL and credentials","Retry the commit if the error was transient (connection drop); otherwise fix the underlying DB issue before retrying"],"exampleFix":"// before: opaque failure\ntry {\n  viewOps.commit(...);\n} catch (UncheckedSQLException e) {\n  LOG.error(\"commit failed: {}\", e.getMessage()); // \"Unknown failure\"\n}\n// after: surface the real cause\ntry {\n  viewOps.commit(...);\n} catch (UncheckedSQLException e) {\n  LOG.error(\"view commit failed\", e.getCause()); // actual SQLException\n}","handlingStrategy":"try-catch","validationCode":"// check DB reachability & privileges before committing\ntry (Connection c = dataSource.getConnection()) {\n  try (Statement s = c.createStatement()) {\n    s.executeQuery(\"SELECT 1 FROM iceberg_views LIMIT 1\"); // table exists & readable\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  viewOps.commit(request);\n} catch (UncheckedSQLException e) {\n  SQLException cause = e.getCause();\n  LOG.error(\"View commit failed for {}\", viewId, cause); // inspect real SQL error\n  if (isTransient(cause)) retryWithBackoff();\n}","preventionTips":["Always log the causal SQLException, never just 'Unknown failure'","Keep the JDBC catalog schema in sync with your Iceberg version","Grant the catalog DB user full DML on iceberg_tables/iceberg_views","Monitor DB connectivity and lock timeouts"],"tags":["jdbc","sql","catalog-commit","database"],"backgroundTag":"database-write-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"}