apache/beam · error · IllegalArgumentException

Unhandled type as method argument: ${type}

Error message

Unhandled type as method argument: ${type}

What it means

When generating DoFn invoker bytecode, this factory maps JVM argument types to bytecode opcodes for loading/storing locals. If a method argument's type (an int from org.objectweb.asm.Type) is not one of the handled primitives/reference kinds, it throws this IllegalArgumentException. It is an internal invariant violation: it means the signature analysis produced an argument type the bytecode emitter does not know how to handle.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/reflect/ByteBuddyDoFnInvokerFactory.java:1482

    }

    private Object describeType(Type type) {
      switch (type.getSort()) {
        case Type.OBJECT:
          return type.getInternalName();
        case Type.INT:
        case Type.BYTE:
        case Type.BOOLEAN:
        case Type.SHORT:
          return Opcodes.INTEGER;
        case Type.LONG:
          return Opcodes.LONG;
        case Type.DOUBLE:
          return Opcodes.DOUBLE;
        case Type.FLOAT:
          return Opcodes.FLOAT;
        default:
          throw new IllegalArgumentException("Unhandled type as method argument: " + type);
      }
    }

    private void visitFrame(
        MethodVisitor mv, boolean localsIncludeReturn, @Nullable String stackTop) {
      boolean hasReturnLocal = (returnVarIndex != null) && localsIncludeReturn;

      Type[] localTypes = Type.getArgumentTypes(instrumentedMethod.getDescriptor());
      Object[] locals = new Object[1 + localTypes.length + (hasReturnLocal ? 1 : 0)];
      TypeDescription.Generic receiverType =
          checkStateNotNull(
              instrumentedMethod.getReceiverType(),
              "invalid static method used as annotated DoFn method");
      locals[0] = receiverType.asErasure().getInternalName();
      for (int i = 0; i < localTypes.length; i++) {
        locals[i + 1] = describeType(localTypes[i]);
      }
      if (hasReturnLocal) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the DoFn method parameters against the documented allowed ones (ProcessContext, BoundedWindow, timestamp, Duration, Instant, element types) and remove unsupported ones.
2. Upgrade/align to a Beam version where this emitter bug is fixed; check JIRA for 'Unhandled type as method argument'.
3. Align the org.ow2.asm ASM dependency version with the one Beam expects (shading/convergence issue).
4. If reproducible on a supported signature, file a Beam bug with the DoFn signature and full stack trace.

Example fix

// before: unsupported param on DoFn method
@ProcessElement
public void processElement(ProcessContext c, SomeCustomType helper) { ... }
// after: keep only supported params, capture helper in constructor
@ProcessElement
public void processElement(ProcessContext c) { useHelper(c); }

for (Method m : myDoFn.getClass().getDeclaredMethods()) {
  if (m.isAnnotationPresent(OnTimer.class) || m.isAnnotationPresent(ProcessElement.class)) {
    for (Class<?> p : m.getParameterTypes()) {
      if (!isSupportedDoFnParam(p)) {
        throw new IllegalStateException("Unsupported DoFn param " + p + " on " + m);
      }
    }
  }
}

When it happens

Trigger: Building an invoker for a DoFn whose @ProcessElement/@OnTimer method has a parameter type the emitter's switch (INT/LONG/DOUBLE/FLOAT/reference) does not cover — effectively any code path where ASM Type sorting yields an unexpected sort value; in practice a bug trigger rather than user error, reached via DoFnInvoker.newInvoker on unusual DoFn signatures.

Common situations: Exotic parameter types in DoFn methods after signature-erasure edge cases; Beam version bugs where a new parameter kind (e.g. additional annotation-injected parameters) wasn't added to this switch; repackaged bytecode where ASM Type constants differ across ASM versions on the classpath.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Failed to locate DefaultGetSize.validateSize()
• Unable to construct @OnTimer invoker for ${className}
• Unable to construct @OnTimerFamily invoker for ${className}
• error when invoking Coder factory method
• cannot register Coder : does not have an accessible method n

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