apache/beam · error · IllegalArgumentException

Encountered UNSPECIFIED AtomicType

Error message

Encountered UNSPECIFIED AtomicType

What it means

fieldTypeFromProtoWithoutNullable switches on the proto FieldType's type and, upon AtomicType UNSPECIFIED, throws IllegalArgumentException. UNSPECIFIED means the producer did not set an atomic type at all, so the field type cannot be reconstructed.

Source

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

            return FieldType.of(TypeName.BYTE);
          case INT16:
            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();

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the producer to set a concrete AtomicType (e.g. STRING, INT64, BOOLEAN, BYTES) for every atomic field.
2. Validate the proto before decoding: check protoFieldType.getAtomicType() != UNSPECIFIED.
3. If the data is legacy, re-encode the schema with a correct Beam SDK version.
4. Catch the IllegalArgumentException at schema decode and reject the record.

Example fix

// before (producer)
FieldType.Builder b = FieldType.newBuilder(); // atomic_type never set
// after
FieldType.Builder b = FieldType.newBuilder().setAtomicType(AtomicType.STRING);

if (protoFieldType.getTypeCase() == FieldType.TypeCase.ATOMIC_TYPE
    && protoFieldType.getAtomicType() == AtomicType.UNSPECIFIED) {
  throw new IllegalArgumentException("Field has UNSPECIFIED atomic type");
}

boolean hasAtomicType(SchemaApi.FieldType ft) {
  return ft.getTypeCase() == SchemaApi.FieldType.TypeCase.ATOMIC_TYPE
      && ft.getAtomicType() != SchemaApi.AtomicType.UNSPECIFIED;
}

When it happens

Trigger: Decoding a FieldType proto whose atomic_type field was never set (UNSPECIFIED) — typically a proto written by buggy or foreign code, or a proto truncated/mis-serialized.

Common situations: Manually building SchemaApi protos without setting atomic_type; data produced by another system's schema exporter; corrupted messages crossing service boundaries.

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

• Failed to decode Schema due to an error decoding Field proto
• Cannot provide a coder for a Beam Row. Please provide a sche
• Could not decode bytes as message
• Could not encode message as bytes
• Encountered unknown AtomicType: +protoFieldType.getAtomicTyp

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