apache/beam · error · SqlUtil.newContextException

Attempting to create catalog

Error message

Attempting to create catalog '%s' with unexpected Calcite Schema of type %s

What it means

Thrown by SqlCreateCatalog.execute when the schema resolved for the catalog name is not a CatalogManagerSchema. CREATE CATALOG can only be executed when the target resolves to Beam's catalog manager schema; any other Calcite Schema type is rejected.

Solutions

1. Run CREATE CATALOG only at the top-level catalog manager scope (no database prefix).
2. Remove any database qualifier from the catalog name so it resolves to CatalogManagerSchema.
3. Verify the Beam SQL session is initialized with the catalog manager schema enabled.
4. Use CREATE DATABASE for database-level DDL instead.

Example fix

// before
CREATE CATALOG mydb.mycatalog ...; -- resolves to a database schema
// after
CREATE CATALOG mycatalog TYPE '...';

// Java: ensure the target schema is the catalog manager before CREATE CATALOG
Schema schema = pair.left.schema;
if (!(schema instanceof CatalogManagerSchema)) {
  throw new IllegalStateException("CREATE CATALOG must target the catalog manager, got " + schema.getClass());
}

boolean isCatalogManagerSchema(Schema s) { return s instanceof org.apache.beam.sdk.extensions.sql.impl.CatalogManagerSchema; }

When it happens

Trigger: Executing `CREATE CATALOG name ...` where SqlDdlNodes.schema(context, true, catalogName) resolves to a schema that is not an instance of CatalogManagerSchema.

Common situations: Issuing CREATE CATALOG in a session whose current schema is a plain BeamCalciteSchema, nested catalog names resolving to a database schema, or mixing Beam SQL with an external Calcite setup.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Attempting to alter catalog
• Attempting to create database
• Attempting to drop a catalog
• Attempting to drop a table using unexpected Calcite Schema…
• Cannot drop catalog: ' ' not found.

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

Appendix: source

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

                "Unexpected properties entry '%s' of class '%s'", property, property.getClass()));
        SqlNodeList kv = ((SqlNodeList) property);

        kv.get(0).unparse(writer, leftPrec, rightPrec); // key
        writer.keyword("=");
        kv.get(1).unparse(writer, leftPrec, rightPrec); // value
      }
      writer.keyword(")");
    }
  }

  @Override
  public void execute(CalcitePrepare.Context context) {
    final Pair<CalciteSchema, String> pair = SqlDdlNodes.schema(context, true, catalogName);
    Schema schema = pair.left.schema;
    String typeStr = checkArgumentNotNull(SqlDdlNodes.getString(type));

    if (!(schema instanceof CatalogManagerSchema)) {
      throw SqlUtil.newContextException(
          catalogName.getParserPosition(),
          RESOURCE.internal(
              "Attempting to create catalog '"
                  + SqlDdlNodes.name(catalogName)
                  + "' with unexpected Calcite Schema of type "
                  + schema.getClass()));
    }

    ((CatalogManagerSchema) schema)
        .createCatalog(catalogName, typeStr, parseProperties(), getReplace(), ifNotExists);
  }

  private Map<String, String> parseProperties() {
    if (properties == null || properties.isEmpty()) {
      return Collections.emptyMap();
    }

    Map<String, String> props = new HashMap<>();

View on GitHub (pinned to 12126d8942)