apache/iceberg · error · UncheckedSQLException

Failed to execute query: %s

Error message

Failed to execute query: %s

What it means

The fetch() helper runs SQL queries (SELECT via RowProducer) and wraps any SQLException into UncheckedSQLException with "Failed to execute query: %s". Unlike execute(), fetch does not funnel errors through sqlErrorHandler, so all query failures surface here.

Source

Thrown at core/src/main/java/org/apache/iceberg/jdbc/JdbcCatalog.java:813

          conn -> {
            List<R> result = Lists.newArrayList();

            try (PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
              for (int pos = 0; pos < args.length; pos += 1) {
                preparedStatement.setString(pos + 1, args[pos]);
              }

              try (ResultSet rs = preparedStatement.executeQuery()) {
                while (rs.next()) {
                  result.add(toRow.apply(rs));
                }
              }
            }

            return result;
          });
    } catch (SQLException e) {
      throw new UncheckedSQLException(e, "Failed to execute query: %s", sql);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new UncheckedInterruptedException(e, "Interrupted in SQL query");
    }
  }

  private Map<String, String> fetchProperties(Namespace namespace) {
    if (!namespaceExists(namespace)) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
    }

    String namespaceName = JdbcUtil.namespaceToString(namespace);

    List<Map.Entry<String, String>> entries =
        fetch(
            row ->
                new AbstractMap.SimpleImmutableEntry<>(
                    row.getString(JdbcUtil.NAMESPACE_PROPERTY_KEY),

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the chained SQLException cause for the database-level reason
2. Verify connectivity (URL, credentials, network) and that catalog tables exist
3. Align the catalog schema with the Iceberg version in use (re-initialize or migrate tables)
4. Grant SELECT privileges on the catalog tables to the configured user

Example fix

// before
List<TableIdentifier> tables = catalog.listTables(ns);
// after
try {
  List<TableIdentifier> tables = catalog.listTables(ns);
} catch (UncheckedSQLException e) {
  LOG.error("Query failed: {}", e.getCause().getMessage());
  throw e;
}

try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
  // ensure catalog tables are present before listing
  DatabaseMetaData md = c.getMetaData();
  ResultSet rs = md.getTables(null, null, icebergCatalogTableName, null);
  if (!rs.next()) throw new IllegalStateException("Catalog table missing; call initializeCatalogTables");
}

try {
  List<TableIdentifier> tables = catalog.listTables(ns);
} catch (UncheckedSQLException e) {
  LOG.error("Catalog query failed: {}", e.getCause().getMessage(), e.getCause());
  throw e;
}

When it happens

Trigger: Calling listTables, listNamespaces, listViews, or entries (and any fetch-based read) when the query fails: connection loss, SQL syntax error from a mismatched/legacy catalog schema, missing catalog tables, or permission denied on SELECT.

Common situations: Upgrading Iceberg against a JDBC catalog created by an older version (schema drift); DB network outage; user lacking SELECT grants; catalog table accidentally dropped or moved to another schema.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• Cannot initialize JDBC catalog
• Cannot check and eventually update SQL schema
• Failed to execute: %s
• Failed to get table %s from catalog %s
• Failed to execute exists query: %s

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/e871ce6e02f00a98. Report an issue: GitHub.