apache/beam · error · SqlUtil.newContextException

Attempting to create a table with unexpected Calcite Schema…

Error message

Attempting to create a table with unexpected Calcite Schema of type %s

What it means

Internal invariant error in SqlCreateExternalTable.execute: after resolving the schema, Beam expects it to be either a CatalogManagerSchema-resolvable catalog schema or a BeamCalciteSchema. Any other Calcite Schema implementation cannot host a Beam external table, so the DDL aborts with RESOURCE.internal.

Solutions

1. Register a BeamCalciteSchema (or a CatalogManagerSchema-managed catalog) as the target schema for Beam SQL DDL
2. Use the default Beam SQL catalog/database instead of a custom root schema
3. If embedding, wrap your schema via Beam's schema provider APIs rather than raw CalciteSchema
4. File/inspect Beam issue if this occurs with a stock setup

Example fix

// before
rootSchema.add("mydb", new AbstractSchema()); // plain Calcite schema
// after
rootSchema.add("mydb", BeamCalciteSchema.create(new BeamSqlTable...schema)); // or use CatalogManagerSchema

if (!(schema instanceof BeamCalciteSchema) && !(schema instanceof CatalogManagerSchema)) {
  throw new IllegalArgumentException("CREATE EXTERNAL TABLE requires a Beam-managed schema");
}

boolean isBeamSchema(Schema s) {
  return s instanceof BeamCalciteSchema || s instanceof CatalogManagerSchema;
}

When it happens

Trigger: CREATE EXTERNAL TABLE executed against a Calcite schema that is neither a catalog-managed schema yielding a BeamCalciteSchema nor a BeamCalciteSchema itself — e.g. a custom/plain CalciteSchema registered into the connection's root schema.

Common situations: Embedding Beam SQL with a hand-built Calcite SchemaPlus; plugging third-party Calcite adapters into Beam's DDL path; test harnesses that register plain CalciteTest schemas.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Attempting to drop a catalog
• Attempting to drop a table using unexpected Calcite Schema…
• Attempting to drop database
• Attempting to alter catalog
• Attempting to create catalog

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

Appendix: source

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

            name.getParserPosition(), RESOURCE.tableExists(pair.right));
      }
      return;
    }

    Schema schema = pair.left.schema;

    BeamCalciteSchema beamCalciteSchema;
    if (schema instanceof CatalogManagerSchema) {
      TableName pathOverride = TableName.create(name.toString());
      CatalogManagerSchema catalogManagerSchema = (CatalogManagerSchema) schema;
      catalogManagerSchema.maybeRegisterProvider(pathOverride, SqlDdlNodes.getString(type));

      CatalogSchema catalogSchema = catalogManagerSchema.getCatalogSchema(pathOverride);
      beamCalciteSchema = catalogSchema.getDatabaseSchema(pathOverride);
    } else if (schema instanceof BeamCalciteSchema) {
      beamCalciteSchema = (BeamCalciteSchema) schema;
    } else {
      throw SqlUtil.newContextException(
          name.getParserPosition(),
          RESOURCE.internal(
              "Attempting to create a table with unexpected Calcite Schema of type "
                  + schema.getClass()));
    }
    Table table = toTable();

    if (partitionFields != null) {
      checkArgument(
          beamCalciteSchema.getTableProvider().supportsPartitioning(table),
          "Invalid use of 'PARTITIONED BY()': Table '%s' of type '%s' "
              + "does not support partitioning.",
          name(name),
          SqlDdlNodes.getString(type));
    }

    beamCalciteSchema.getTableProvider().createTable(table);
  }

View on GitHub (pinned to 12126d8942)