apache/beam · error · IllegalArgumentException

Encountered unknown AtomicType: +protoFieldType.getAtomicTyp

Error message

Encountered unknown AtomicType: +protoFieldType.getAtomicType()

What it means

The default branch of the AtomicType switch throws IllegalArgumentException 'Encountered unknown AtomicType: ...' when the proto contains an atomic type value this SDK does not recognize. This is forward-compatibility protection against newer enum values.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/SchemaTranslation.java:380

            return FieldType.of(TypeName.INT16);
          case INT32:
            return FieldType.of(TypeName.INT32);
          case INT64:
            return FieldType.of(TypeName.INT64);
          case FLOAT:
            return FieldType.of(TypeName.FLOAT);
          case DOUBLE:
            return FieldType.of(TypeName.DOUBLE);
          case STRING:
            return FieldType.of(TypeName.STRING);
          case BOOLEAN:
            return FieldType.of(TypeName.BOOLEAN);
          case BYTES:
            return FieldType.of(TypeName.BYTES);
          case UNSPECIFIED:
            throw new IllegalArgumentException("Encountered UNSPECIFIED AtomicType");
          default:
            throw new IllegalArgumentException(
                "Encountered unknown AtomicType: " + protoFieldType.getAtomicType());
        }
      case ROW_TYPE:
        return FieldType.row(schemaFromProto(protoFieldType.getRowType().getSchema()));
      case ARRAY_TYPE:
        return FieldType.array(fieldTypeFromProto(protoFieldType.getArrayType().getElementType()));
      case ITERABLE_TYPE:
        return FieldType.iterable(
            fieldTypeFromProto(protoFieldType.getIterableType().getElementType()));
      case MAP_TYPE:
        return FieldType.map(
            fieldTypeFromProto(protoFieldType.getMapType().getKeyType()),
            fieldTypeFromProto(protoFieldType.getMapType().getValueType()));
      case LOGICAL_TYPE:
        SchemaApi.LogicalType logicalType = protoFieldType.getLogicalType();
        String urn = logicalType.getUrn();
        Class<? extends LogicalType<?, ?>> logicalTypeClass = STANDARD_LOGICAL_TYPES.get(urn);
        if (logicalTypeClass != null) {

View on GitHub (pinned to 12126d8942)

Solutions

Upgrade the reading SDK to the same or newer Beam version that knows the AtomicType.
Pin matching Beam versions across writer and reader in the pipeline.
If immediate upgrade is impossible, re-encode the data with supported field types.
Catch the IllegalArgumentException during decode to isolate/redirect bad records rather than failing the whole pipeline.

Example fix

// build.gradle (reader)
// before: implementation 'org.apache.beam:beam-sdks-java-core:2.30.0'
// after:  implementation 'org.apache.beam:beam-sdks-java-core:2.61.0'

Defensive patterns

Strategy: try-catch

Validate before calling

int v = protoFieldType.getAtomicTypeValue(); // or ordinal via descriptor
if (protoFieldType.getAtomicType().getDescriptor().getOptions()
    .hasDeprecated()) { /* handle */ }

Try / catch

try {
  return fieldTypeFromProto(protoFieldType);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Encountered unknown AtomicType")) {
    return fallbackFieldType; // or rethrow with version info
  }
  throw e;
}

Prevention

Pin identical Beam versions for writers and readers.
Upgrade the reader SDK when new AtomicType values appear upstream.
Test schema compatibility in CI across supported Beam versions.
Avoid custom forks of SchemaApi protos.

When it happens

Trigger: Decoding a schema proto produced by a newer Beam version (or another runtime) that uses an AtomicType enum value unknown to the current SDK.

Common situations: Beam version skew: writer on Beam 2.x-newer, reader on older SDK; custom forks adding enum values; mixed-version streaming pipelines.

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/1a3a5e31d6401085. Report an issue: GitHub.