apache/beam · error · IllegalArgumentException

Cannot find a matching Calcite SqlTypeName for Beam type

Error message

Cannot find a matching Calcite SqlTypeName for Beam type: %s

What it means

In CalciteUtils.toSqlTypeName, if a Schema.TypeName falls into the default case and has no direct Calcite SqlTypeName counterpart, IllegalArgumentException 'Cannot find a matching Calcite SqlTypeName for Beam type: %s' is thrown. It means a Beam primitive/atomic type cannot be represented in Calcite's type system for SQL planning.

Solutions

Replace the unsupported FieldType with a SQL-mappable type (string, int64, double, timestamp, etc.).
Wrap complex types as ROW/ARRAY/MAP explicitly via the supported SQL mappings.
Log and skip such fields before building the SQL schema.
Upgrade Beam — mapping coverage grows over versions.

Example fix

// before
Schema.Field.of("blob", FieldType.varbinary()) // may be unmapped in older Beam
// after
Schema.Field.of("blob", FieldType.bytes.withNullable(true)) // or a supported type

Defensive patterns

Strategy: try-catch

Validate before calling

if (!Set.of(TypeName.BYTE, TypeName.INT16, TypeName.INT32, TypeName.INT64, TypeName.FLOAT, TypeName.DOUBLE, TypeName.DECIMAL, TypeName.STRING, TypeName.BOOLEAN, TypeName.DATETIME).contains(fieldType.getTypeName())) { /* handle before conversion */ }

Type guard

boolean isCalciteMappable(Schema.TypeName t) {
  return switch (t) { case BYTE, INT16, INT32, INT64, FLOAT, DOUBLE, DECIMAL, STRING, BOOLEAN, DATETIME -> true; default -> false; };
}

Try / catch

try { rel = CalciteUtils.toRelDataType(fieldType, typeFactory); }
catch (IllegalArgumentException e) { /* skip field or map to nearest supported type */ }

Prevention

Restrict SQL-exposed schemas to primitive SQL-representable types
Model complex data as ROW/ARRAY/MAP explicitly
Test schema -> RelDataType conversion in CI for all table schemas
Keep Beam upgraded for expanded type coverage

When it happens

Trigger: Passing a Schema.FieldType whose TypeName (e.g. BYTE_ARRAY in some paths, ROW without prior handling, DATETIME variants, or any unsupported TypeName) reaches the default branch of toSqlTypeName.

Common situations: Creating tables or deriving RelDataType from a schema that contains types Beam SQL cannot map (e.g. logical/logical-row types added after CalciteUtils was written), or hand-built schemas used with SqlTransform.

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

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

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/utils/CalciteUtils.java:243

          if (logicalType != null) {
            if (logicalType instanceof PassThroughLogicalType) {
              // for pass through logical type, just return its base type
              return toSqlTypeName(logicalType.getBaseType());
            } else if (Timestamp.IDENTIFIER.equals(logicalType.getIdentifier())) {
              return SqlTypeName.TIMESTAMP;
            } else if ("SqlCharType".equals(logicalType.getIdentifier())) {
              LOG.warn(
                  "SqlCharType is used in Schema. It was removed in Beam 2.44.0 and should be"
                      + " replaced by FixedString logical type.");
              return SqlTypeName.CHAR;
            } else {
              throw new IllegalArgumentException(
                  String.format(
                      "Cannot find a matching Calcite SqlTypeName for Beam logical type: %s",
                      logicalType.getIdentifier()));
            }
          }
          throw new IllegalArgumentException(
              String.format("Cannot find a matching Calcite SqlTypeName for Beam type: %s", type));
        } else {
          return typeName;
        }
    }
  }

  public static FieldType toFieldType(SqlTypeNameSpec sqlTypeName) {
    return toFieldType(
        Preconditions.checkArgumentNotNull(
            SqlTypeName.get(sqlTypeName.getTypeName().getSimple()),
            "Failed to find Calcite type with name '%s'",
            sqlTypeName.getTypeName().getSimple()));
  }

  public static FieldType toFieldType(SqlTypeName sqlTypeName) {
    switch (sqlTypeName) {
      case MAP:

View on GitHub (pinned to 12126d8942)