{"record":{"id":"896dd991bcac190e","repo":"apache/iceberg","slug":"failed-to-execute-exists-query-s","errorCode":null,"errorMessage":"Failed to execute exists query: %s","messagePattern":"Failed to execute exists query: (.+?)","errorType":"exception","errorClass":"UncheckedSQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/jdbc/JdbcUtil.java","lineNumber":829,"sourceCode":"    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              try (ResultSet rs = preparedStatement.executeQuery()) {\n                if (rs.next()) {\n                  return true;\n                }\n              }\n            }\n\n            return false;\n          });\n    } catch (SQLException e) {\n      throw new UncheckedSQLException(e, \"Failed to execute exists query: %s\", sql);\n    } catch (InterruptedException e) {\n      Thread.currentThread().interrupt();\n      throw new UncheckedInterruptedException(e, \"Interrupted in SQL query\");\n    }\n  }\n}\n","sourceCodeStart":811,"sourceCodeEnd":836,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/jdbc/JdbcUtil.java#L811-L836","documentation":"JdbcUtil.exists runs a user-supplied existence query (tableExists, viewExists, namespaceExists) inside interruptible SQL execution. Any SQLException is wrapped in UncheckedSQLException as 'Failed to execute exists query: <sql>' so callers see the exact SQL that failed alongside the driver's cause. It indicates the catalog metadata database could not answer the existence probe.","triggerScenarios":"Catalog DB unreachable or credentials expired when checking tableExists/viewExists/namespaceExists; the underlying catalog table (jdbc_tables/jdbc_namespaces) missing from a not-yet-initialized DB; SQL syntax/dialect error in the versioned query (schema V0 vs V1 mismatch); permissions lacking SELECT.","commonSituations":"Fresh JDBC catalog pointing at an empty database; Postgres/MySQL user without grants; network blip between compute engine and metadata DB; driver upgrade changing error semantics.","solutions":["Inspect the chained SQLException cause for the vendor error code (connection refused, unknown table, access denied)","Initialize the JDBC catalog schema (run the DDL that creates jdbc_tables/jdbc_namespaces) on the target DB","Check DB connectivity and credentials in the jdbc catalog properties (uri, user, password)","Grant SELECT on the catalog tables to the configured DB user; verify the schema-version property matches the DB layout"],"exampleFix":"// before\nJdbcCatalog catalog = new JdbcCatalog(); // configured against empty DB\ncatalog.tableExists(ident); // UncheckedSQLException: Failed to execute exists query\n// after\n// pre-create catalog schema, e.g. for Postgres:\n// CREATE TABLE IF NOT EXISTS jdbc_tables (...); CREATE TABLE IF NOT EXISTS jdbc_namespaces (...);\nJdbcCatalog catalog = catalogWithInitializedDb();","handlingStrategy":"try-catch","validationCode":"// before catalog ops, verify DB reachable:\ntry (Connection c = DriverManager.getConnection(jdbcUri, user, pass)) { /* simple SELECT 1 */ }","typeGuard":null,"tryCatchPattern":"try { catalog.tableExists(identifier); } catch (UncheckedSQLException e) { SQLException cause = (SQLException) e.getCause(); LOG.error(\"exists query failed: state={} code={}\", cause.getSQLState(), cause.getErrorCode(), cause); }","preventionTips":["Run catalog DDL initialization before first connection to a new DB","Health-check DB connectivity in deployment before starting jobs","Grant the DB user SELECT on jdbc_tables/jdbc_namespaces","Pin the jdbc schema-version property to the actual DB schema layout"],"tags":["jdbc","sql","existence-check","database"],"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"}