apache/beam · error · UnsupportedOperationException

Unable to convert logical type ${identifier}

Error message

Unable to convert logical type ${identifier}

What it means

When converting Calcite values back to Beam Row objects, toBeamObject maps each FieldType, including logical types. If a field's logical type identifier is not one of the supported ones and is not a PassThroughLogicalType, this UnsupportedOperationException is thrown. Beam SQL's Calcite bridge only understands a fixed set of logical types.

Source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/rel/BeamCalcRel.java:469

        } else if (SqlTypes.DATETIME.getIdentifier().equals(identifier)) {
          if (value instanceof Timestamp) {
            value = SqlFunctions.toLong((Timestamp) value);
          }
          return LocalDateTime.of(
              LocalDate.ofEpochDay(((Number) value).longValue() / MILLIS_PER_DAY),
              LocalTime.ofNanoOfDay(
                  (((Number) value).longValue() % MILLIS_PER_DAY) * NANOS_PER_MILLISECOND));
        } else if (org.apache.beam.sdk.schemas.logicaltypes.Timestamp.IDENTIFIER.equals(
            identifier)) {
          if (value instanceof Timestamp) {
            value = SqlFunctions.toLong((Timestamp) value);
          }
          return java.time.Instant.ofEpochMilli(((Number) value).longValue());
        } else {
          if (logicalType instanceof PassThroughLogicalType) {
            return toBeamObject(value, logicalType.getBaseType(), verifyValues);
          }
          throw new UnsupportedOperationException("Unable to convert logical type " + identifier);
        }
      default:
        throw new UnsupportedOperationException("Unable to convert " + fieldType.getTypeName());
    }
  }

  private static List<Object> toBeamList(
      List<Object> arrayValue, FieldType elementType, boolean verifyValues) {
    return arrayValue.stream()
        .map(e -> toBeamObject(e, elementType, verifyValues))
        .collect(Collectors.toList());
  }

  private static Map<Object, Object> toBeamMap(
      Map<Object, Object> mapValue,
      FieldType keyType,
      FieldType elementType,
      boolean verifyValues) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Implement PassThroughLogicalType (based on a supported base type) for your custom logical type so it passes through conversion
2. Convert the column to a supported base type before the SQL query (e.g. store as VARCHAR/LONG)
3. Map the logical type back to a primitive in the schema before running the query
4. Check whether your Beam version supports the logical type in the SQL extension; upgrade if a newer release added support

Example fix

// before
FieldType.of(LogicalTypes.myCustomType());
// after
Schema.FieldType.of(new PassThroughLogicalType<>(...baseType VARCHAR...)); // or use VARCHAR directly

boolean sqlConvertible(Schema.FieldType t) {
  var lt = t.getLogicalType();
  return lt == null || lt instanceof PassThroughLogicalType || isSupportedIdentifier(lt.getIdentifier());
}

boolean isSupported(Schema.FieldType f) {
  return f.getLogicalType() == null || f.getLogicalType() instanceof PassThroughLogicalType;
}

try {
  Row beamRow = BeamCalcRel.toRow(calciteRow, schema, verify);
} catch (UnsupportedOperationException e) {
  // fall back to manual conversion for the custom logical type
}

When it happens

Trigger: A Beam Schema field uses a custom LogicalType (or one not supported by the SQL integration, e.g. some non-pass-through logical types like bytes-backed or enum variants) and the row passes through BeamCalcRel.toRow / toBeamObject conversion.

Common situations: Using a custom Schema.LogicalType defined in user code and then selecting that column in a Beam SQL query; SDK/version mismatch where a logical type added upstream isn't supported by the SQL extension yet.

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

• Unable to convert ${typeName}
• Unable to find value #${index}
• Unable to get logical type ${identifier}
• Unable to get ${typeName}
• '${fieldName}' field is invalid at the top level for Kafka i

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