apache/beam · error · IllegalArgumentException

Unknown watermark type: ${type}. Supported types are Process

Error message

Unknown watermark type: ${type}. Supported types are ProcessingTime, LogAppendTime, CreateTime.

What it means

Thrown by KafkaTableProvider.buildBeamSqlTable when the DDL table property 'watermark.type' (mapped from the TBLPROPERTIES 'type') is not one of ProcessingTime, LogAppendTime, or CreateTime. The switch over the watermark type string has a default branch that rejects any unrecognized value at table-creation time.

Source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/kafka/KafkaTableProvider.java:143

      String type = properties.get("watermark.type").asText().toUpperCase();

      switch (type) {
        case "PROCESSINGTIME":
          timestampPolicyFactory = TimestampPolicyFactory.withProcessingTime();
          break;
        case "LOGAPPENDTIME":
          timestampPolicyFactory = TimestampPolicyFactory.withLogAppendTime();
          break;
        case "CREATETIME":
          Duration delay = Duration.ZERO;
          if (properties.has("watermark.delay")) {
            String delayStr = properties.get("watermark.delay").asText();
            delay = PeriodFormat.getDefault().parsePeriod(delayStr).toStandardDuration();
          }
          timestampPolicyFactory = TimestampPolicyFactory.withCreateTime(delay);
          break;
        default:
          throw new IllegalArgumentException(
              "Unknown watermark type: "
                  + type
                  + ". Supported types are ProcessingTime, LogAppendTime, CreateTime.");
      }
    }

    BeamKafkaTable kafkaTable = null;
    if (Schemas.isNestedSchema(schema)) {
      Optional<PayloadSerializer> serializer =
          payloadFormat.map(
              format ->
                  PayloadSerializers.getSerializer(
                      format,
                      checkArgumentNotNull(schema.getField(PAYLOAD_FIELD).getType().getRowSchema()),
                      TableUtils.convertNode2Map(properties)));
      kafkaTable =
          new NestedPayloadKafkaTable(
              schema, bootstrapServers, topics, serializer, timestampPolicyFactory);

View on GitHub (pinned to 12126d8942)

Solutions

Set 'watermark.type' to exactly ProcessingTime, LogAppendTime, or CreateTime (match capitalization).
If no watermark behavior is needed, omit the 'watermark.type' property so the default policy is used.
Check the Kafka SQL provider docs for the exact supported enum values for your Beam version.

Example fix

// before
CREATE EXTERNAL TABLE kafka_table (...) TBLPROPERTIES {'type':'processingtime'}
// after
CREATE EXTERNAL TABLE kafka_table (...) TBLPROPERTIES {'type':'ProcessingTime'}

Defensive patterns

Strategy: validation

Validate before calling

Set<String> allowed = Set.of("ProcessingTime", "LogAppendTime", "CreateTime");
if (watermarkType != null && !allowed.contains(watermarkType)) {
  throw new IllegalArgumentException("watermark.type must be one of " + allowed);
}

Try / catch

try { table = tableProvider.buildBeamSqlTable(table); } catch (IllegalArgumentException e) { /* fall back to default watermark policy */ }

Prevention

Copy the exact enum-capitalized names from the docs
Omit the property when the default policy suffices
Add a startup DDL validation test

When it happens

Trigger: Creating a Beam SQL Kafka table whose 'watermark.type' property is misspelled (e.g. 'procesingtime'), lowercase ('processingtime'), or an entirely unsupported policy string; the parser hits the default branch and throws IllegalArgumentException.

Common situations: Typo in CREATE EXTERNAL TABLE TBLPROPERTIES; copying a watermark type from another connector (e.g. Flink) that supports extra values; case-sensitivity mistakes; upgrading Beam and using a value documented elsewhere but not implemented in this provider.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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