apache/iceberg · error · TableNotExistException

TableNotExistException

Error message

TableNotExistException

What it means

FlinkCatalog.loadIcebergTable converts Iceberg's NoSuchTableException into Flink's TableNotExistException. It means the requested table (in its database) does not exist in the underlying Iceberg catalog when a Flink operation tries to load the Iceberg table — raised in loadIcebergTable, used by table/alterTable.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:375

    ImmutableMap.Builder<String, String> mergedProps = ImmutableMap.builder();
    mergedProps.put(
        FlinkCreateTableOptions.CONNECTOR_PROPS_KEY, FlinkDynamicTableFactory.FACTORY_IDENTIFIER);
    mergedProps.put(FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY, srcCatalogProps);
    mergedProps.putAll(tableProps);

    return toCatalogTableWithProps(table, mergedProps.build());
  }

  private Table loadIcebergTable(ObjectPath tablePath) throws TableNotExistException {
    try {
      Table table = icebergCatalog.loadTable(toIdentifier(tablePath));
      if (cacheEnabled) {
        table.refresh();
      }

      return table;
    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {
      throw new TableNotExistException(getName(), tablePath, e);
    }
  }

  @Override
  public boolean tableExists(ObjectPath tablePath) throws CatalogException {
    return icebergCatalog.tableExists(toIdentifier(tablePath));
  }

  @Override
  public void dropTable(ObjectPath tablePath, boolean ignoreIfNotExists)
      throws TableNotExistException, CatalogException {
    try {
      icebergCatalog.dropTable(toIdentifier(tablePath));
    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {
      if (!ignoreIfNotExists) {
        throw new TableNotExistException(getName(), tablePath, e);
      }
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify existence with tableExists or SHOW TABLES before loading/altering, and use exact casing
2. Confirm the Flink catalog config (catalog type, warehouse, baseNamespace) points to the environment holding the table
3. Refresh/rebuild Flink's catalog cache so stale metadata is discarded
4. If the table was renamed/dropped intentionally, create it again or update the job to reference the new name

Example fix

// before
catalog.alterTable(tablePath, newTable, false); // TableNotExistException if missing
// after
if (catalog.tableExists(tablePath)) {
  catalog.alterTable(tablePath, newTable, false);
} else {
  catalog.createTable(tablePath, newTable);
}

boolean exists = catalog.tableExists(tablePath);

try {
  CatalogTable table = catalog.getTable(tablePath);
} catch (TableNotExistException e) {
  LOG.warn("Table {} not found in catalog {}", tablePath, e.getCatalogName());
}

When it happens

Trigger: Loading or altering a table via tableExists/listTables naming, e.g. ALTER TABLE on a non-existent table, SELECT/DROP on a table deleted externally, or baseNamespace resolution making the actual Iceberg identifier differ from the Flink ObjectPath.

Common situations: Table dropped by another job/session between existence check and load; typo'd table name; environment/catalog misconfiguration pointing at a different warehouse; table exists in Flink's cached metadata but was removed from the Iceberg catalog; case mismatch in table names.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• DatabaseNotEmptyException
• Can not alter the default database when the iceberg catalog
• FunctionNotExistException
• Table not found, skipping commit: {}
• Cannot find table %s to drop

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