apache/iceberg · error · UncheckedSQLException

Failed to get table %s from catalog %s

Error message

Failed to get table %s from catalog %s

What it means

Thrown when reading the table's current metadata row from the JDBC catalog fails with a SQLException. This wraps database-level errors (query failure, connection problem) encountered while fetching the row in jdbc_tables. It is distinct from the table-missing case, which throws NoSuchTableException.

Source

Thrown at core/src/main/java/org/apache/iceberg/jdbc/JdbcTableOperations.java:79

    this.tableIdentifier = tableIdentifier;
    this.fileIO = fileIO;
    this.connections = dbConnPool;
    this.catalogProperties = catalogProperties;
    this.schemaVersion = schemaVersion;
  }

  @Override
  public void doRefresh() {
    Map<String, String> table;

    try {
      table = JdbcUtil.loadTable(schemaVersion, connections, catalogName, tableIdentifier);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new UncheckedInterruptedException(e, "Interrupted during refresh");
    } catch (SQLException e) {
      // SQL exception happened when getting table from catalog
      throw new UncheckedSQLException(
          e, "Failed to get table %s from catalog %s", tableIdentifier, catalogName);
    }

    if (table.isEmpty()) {
      if (currentMetadataLocation() != null) {
        throw new NoSuchTableException(
            "Failed to load table %s from catalog %s: dropped by another process",
            tableIdentifier, catalogName);
      } else {
        this.disableRefresh();
        return;
      }
    }

    String newMetadataLocation = table.get(METADATA_LOCATION_PROP);
    Preconditions.checkState(
        newMetadataLocation != null,
        "Invalid table %s: metadata location is null",

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check database health, connectivity, and server logs at the time of failure.
2. Verify the JDBC catalog schema exists and matches the expected version (run JdbcCatalog schema init/migration).
3. Confirm the catalog user retains SELECT privileges on the jdbc_tables table.
4. Retry the operation if the failure was transient.
5. Inspect the chained SQLException cause for the concrete SQL error code.

Example fix

// before
// catalog DB schema never initialized
Map<String,String> props = Map.of("uri", "jdbc:postgresql://db/iceberg");
// after
// initialize schema first
try (JdbcCatalog c = new JdbcCatalog()) { c.setConf(conf); c.initialize("jdbc", props); }
// or manually run schema creation: CREATE TABLE iceberg_tables (...)

// ensure the catalog schema exists before use
try (var conn = java.sql.DriverManager.getConnection(dbUrl, dbProps);
     var rs = conn.getMetaData().getTables(null, null, "iceberg_tables", null)) {
  if (!rs.next()) throw new IllegalStateException("Run JdbcCatalog schema initialization first");
}

try {
  table.refresh();
} catch (UncheckedSQLException e) {
  // inspect e.getCause() SQLException for SQLState; retry transient codes (08xxx, 40001)
  if (isTransient(e.getCause())) retryWithBackoff(() -> table.refresh());
  else throw e;
}

When it happens

Trigger: JdbcTableOperations.doRefresh() → JdbcUtil.loadTable(...) throws SQLException during the SELECT against the catalog database.

Common situations: Transient DB outage mid-refresh, connection dropped by server, SQL syntax/schema mismatch after a catalog schema-version change, permissions revoked on the catalog tables.

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 execute query: %s
• Failed to execute exists query: %s

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