What causes "Table '%s' not found" in apache/beam?

Create the table first with CREATE TABLE (or CREATE EXTERNAL TABLE) before altering.

apache/beam · error · SqlUtil.newContextException

Table ' ' not found

Error message

Table '%s' not found

What it means

Thrown by SqlAlterTable.execute when beamCalciteSchema.getTable(pair.right) returns null, i.e. the table named in the ALTER TABLE statement does not exist in the resolved schema. Calcite reports it via RESOURCE.tableNotFound with the parser position.

Solutions

Create the table first with CREATE TABLE (or CREATE EXTERNAL TABLE) before altering.
Fix the table name spelling/case and qualify it with the correct database.
Verify the table exists in the resolved schema path (catalog.database).
Re-run any pipeline/steps that register the table if it was dropped elsewhere.

Example fix

// before
ALTER TABLE mydb.orders ADD COLUMN amount DOUBLE; -- 'orders' missing
// after
CREATE TABLE mydb.orders (id BIGINT) ...;
ALTER TABLE mydb.orders ADD COLUMN amount DOUBLE;

Defensive patterns

Strategy: validation

Validate before calling

// Java: check table presence before ALTER TABLE
CalciteSchema dbSchema = ...; // resolved BeamCalciteSchema
if (dbSchema.getTable(tableName) == null) {
  stmt.execute("CREATE TABLE ... "); // or fail fast with a clear message
}
stmt.execute("ALTER TABLE " + tableName + " ...");

Try / catch

// Java
catch (SQLException e) {
  if (e.getMessage().contains("Table '")) {
    throw new IllegalStateException("Table missing; run CREATE TABLE first", e);
  } else throw e;
}

Prevention

Run CREATE TABLE before ALTER TABLE in every script.
Qualify table names with the correct database.
Keep table-name constants centralized to avoid typos.
Check case sensitivity conventions of the catalog.

When it happens

Trigger: Executing `ALTER TABLE name ...` where the resolved BeamCalciteSchema has no table whose name matches pair.right (the table part of the identifier).

Common situations: Typos in table names, running ALTER before CREATE TABLE DDL, tables registered under a different database than the one resolved, or case-sensitive name mismatches.

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

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/2a14ed4225a93f8d. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/parser/SqlAlterTable.java:115

      CatalogManagerSchema catalogManagerSchema = (CatalogManagerSchema) schema;
      CatalogSchema catalogSchema =
          pathOverride.catalog() != null
              ? catalogManagerSchema.getCatalogSchema(pathOverride)
              : catalogManagerSchema.getCurrentCatalogSchema();
      beamCalciteSchema = catalogSchema.getDatabaseSchema(pathOverride);
    } else if (schema instanceof BeamCalciteSchema) {
      beamCalciteSchema = (BeamCalciteSchema) schema;
    } else {
      throw SqlUtil.newContextException(
          name.getParserPosition(),
          RESOURCE.internal(
              "Attempting to drop a table using unexpected Calcite Schema of type "
                  + schema.getClass()));
    }

    if (beamCalciteSchema.getTable(pair.right) == null) {
      // Table does not exist.
      throw SqlUtil.newContextException(
          name.getParserPosition(), RESOURCE.tableNotFound(name.toString()));
    }

    Map<String, String> setPropsMap = SqlDdlNodes.getStringMap(setProps);
    List<String> resetPropsList = SqlDdlNodes.getStringList(resetProps);
    List<String> columnsToDropList = SqlDdlNodes.getStringList(columnsToDrop);
    List<String> partitionsToAddList = SqlDdlNodes.getStringList(partitionsToAdd);
    List<String> partitionsToDropList = SqlDdlNodes.getStringList(partitionsToDrop);

    AlterTableOps alterOps =
        beamCalciteSchema.getTableProvider().alterTable(SqlDdlNodes.name(name));

    if (!setPropsMap.isEmpty() || !resetPropsList.isEmpty()) {
      validateNonOverlappingProps(setPropsMap, resetPropsList);

      alterOps.updateTableProperties(setPropsMap, resetPropsList);
    }
    if (!columnsToDropList.isEmpty() || (columnsToAdd != null && !columnsToAdd.isEmpty())) {

View on GitHub (pinned to 12126d8942)