apache/beam · error · IllegalArgumentException

Cannot find a matching Calcite SqlTypeName for Beam logical…

Error message

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

What it means

CalciteUtils.toSqlTypeName maps Beam Schema types (and legacy logical types) to Calcite SqlTypeName. When a FieldType carries a logical type whose identifier has no known mapping, IllegalArgumentException is thrown with the logical type identifier. This usually means a logical type Beam SQL does not recognize (or a pre-2.44 removed type that is not SqlCharType).

Solutions

1. Replace the custom/legacy logical type with a SQL-representable FieldType (e.g. StringType, FixedString, int64).
2. If you hit a legacy removed type, migrate per the Beam 2.44 migration notes (SqlCharType -> FixedString).
3. Register mapping support by switching on the identifier in your own copy/extension of CalciteUtils.
4. Inspect schema fields and strip logical types before feeding Beam SQL.

Example fix

// before
Schema.Field.of("name", FieldType.logicalType(new SqlCharType()))
// after
Schema.Field.of("name", FieldType.logicalType(FixedString.of(10)))

String id = fieldType.getLogicalType() != null ? fieldType.getLogicalType().getIdentifier() : null;
if (id != null && !SUPPORTED_LOGICAL_IDS.contains(id)) { /* replace or drop field before SQL */ }

boolean isSqlCompatible(FieldType ft) {
  return ft.getLogicalType() == null || Set.of("FixedString", "SqlCharType", "Enumeration", ...).contains(ft.getLogicalType().getIdentifier());
}

try { sqlTypeName = CalciteUtils.toSqlTypeName(fieldType); }
catch (IllegalArgumentException e) { /* substitute a supported FieldType, e.g. FieldType.string() */ }

When it happens

Trigger: toSqlTypeName(FieldType) or toRelDataType with a FieldType whose getLogicalType().getIdentifier() is not one of the handled identifiers (and is not a base type handled by the switch).

Common situations: Using custom logical types registered by the application in a Beam SQL schema; upgrading Beam where a logical type was renamed/removed (e.g. types removed in 2.44 like SqlCharType's siblings); passing non-SQL-compatible logical types such as etc/UTC datetime or enumeration variants.

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

• Cannot find a matching Beam FieldType for Calcite type:
• Cannot find a matching Calcite SqlTypeName for Beam type
• is a type constructor that takes parameters, not a type,so…
• beam.RegisterSchemaProvider: schema type provider for
• Cannot infer types from

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/d917aaff3465acd6. 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:237

          // This will happen e.g. if looking up a STRING type, and metadata isn't set to say which
          // type of SQL string we want. In this case, use the default mapping.
          typeName = BEAM_TO_CALCITE_DEFAULT_MAPPING.get(type);
        }
        if (typeName == null) {
          Schema.LogicalType<?, ?> logicalType = type.getLogicalType();
          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'",

View on GitHub (pinned to 12126d8942)