{"record":{"id":"b77174d04885c52a","repo":"apache/iceberg","slug":"failed-to-execute-s","errorCode":null,"errorMessage":"Failed to execute: %s","messagePattern":"Failed to execute: (.+?)","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java","lineNumber":780,"sourceCode":"  private int execute(String sql, String... args) {\n    return execute(err -> {}, sql, args);\n  }\n\n  private int execute(Consumer<SQLException> sqlErrorHandler, String sql, String... args) {\n    try {\n      return connections.run(\n          conn -> {\n            try (PreparedStatement preparedStatement = conn.prepareStatement(sql)) {\n              for (int pos = 0; pos < args.length; pos += 1) {\n                preparedStatement.setString(pos + 1, args[pos]);\n              }\n\n              return preparedStatement.executeUpdate();\n            }\n          });\n    } catch (SQLException e) {\n      sqlErrorHandler.accept(e);\n      throw new UncheckedSQLException(e, \"Failed to execute: %s\", sql);\n    } catch (InterruptedException e) {\n      throw new UncheckedInterruptedException(e, \"Interrupted in SQL command\");\n    }\n  }\n\n  @FunctionalInterface\n  interface RowProducer<R> {\n    R apply(ResultSet result) throws SQLException;\n  }\n\n  @SuppressWarnings(\"checkstyle:NestedTryDepth\")\n  private <R> List<R> fetch(RowProducer<R> toRow, String sql, String... args) {\n    try {\n      return connections.run(\n          conn -> {\n            List<R> result = Lists.newArrayList();\n\n            try (PreparedStatement preparedStatement = conn.prepareStatement(sql)) {","sourceCodeStart":762,"sourceCodeEnd":798,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java#L762-L798","documentation":"The catalog's execute() helper wraps SQL updates in Tasks; when executeUpdate throws a SQLException that the configured sqlErrorHandler does not consume (convert) into a typed Iceberg exception, it is rethrown as UncheckedSQLException with \"Failed to execute: %s\". It indicates the DML statement (insert/update/delete of catalog metadata) failed at the database level.","triggerScenarios":"Any JdbcCatalog metadata write (create/drop/rename table or view, namespace and property updates) whose prepared statement raises a SQLException not classified as a constraint violation by the error handler: connectivity loss, syntax errors, schema mismatch, lock timeouts, permission denial.","commonSituations":"Database restarted or connection pool exhausted; wrong JDBC URL/credentials; missing table (catalog tables not initialized); DB user lacking INSERT/UPDATE/DELETE grants; deadlocks or lock wait timeouts under concurrent commits.","solutions":["Read the chained SQLException cause for the real database error and fix that underlying issue","Verify JDBC URL, credentials, and that the database is reachable (test connection)","Ensure catalog tables are initialized (initializeCatalogTables) and the user has DML grants","Retry transient failures (locks, deadlocks) and check for long-running transactions holding locks"],"exampleFix":"// before\ncatalog.createNamespace(ns);\n// after\ntry {\n  catalog.createNamespace(ns);\n} catch (UncheckedSQLException e) {\n  LOG.error(\"SQL failed: {}\", e.getCause().getMessage());\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"// Verify connectivity before catalog writes\ntry (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {\n  if (!c.isValid(5)) throw new IllegalStateException(\"DB unreachable\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.createNamespace(ns);\n} catch (UncheckedSQLException e) {\n  Throwable cause = e.getCause();\n  LOG.error(\"Catalog SQL write failed: {}\", cause.getMessage(), cause);\n  if (cause.getMessage().contains(\"connection\")) { /* retry path */ }\n  throw e;\n}","preventionTips":["Always inspect the chained SQLException cause","Use a connection pool with health checks (validation queries)","Grant the catalog user INSERT/UPDATE/DELETE on catalog tables","Keep long transactions short to avoid lock timeouts"],"tags":["jdbc","sql","database","unchecked-exception"],"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"}