apache/beam · error · RuntimeException

Unable to find UserCodeException.wrap

Error message

Unable to find UserCodeException.wrap

What it means

ByteBuddyDoFnInvokerFactory looks up UserCodeException.wrap(Throwable) via getDeclaredMethod to embed user-code exception wrapping into generated DoFn invoker classes. If the method cannot be resolved (missing, renamed, or inaccessible under the active SecurityManager), a RuntimeException with this message is thrown. It signals an inconsistent Beam runtime or a restrictive security policy rather than a user-code bug.

Source

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

        @Nullable Integer returnVarIndex,
        MethodDescription targetMethod,
        MethodDescription instrumentedMethod) {
      this.returnVarIndex = returnVarIndex;
      this.targetMethod = targetMethod;
      this.instrumentedMethod = instrumentedMethod;
      this.returnType = targetMethod.getReturnType().asErasure();

      boolean targetMethodReturnsVoid = TypeDescription.VOID.equals(returnType);
      checkArgument(
          (returnVarIndex == null) == targetMethodReturnsVoid,
          "returnVarIndex should be defined if and only if the target method has a return value");

      try {
        createUserCodeException =
            new MethodDescription.ForLoadedMethod(
                UserCodeException.class.getDeclaredMethod("wrap", Throwable.class));
      } catch (NoSuchMethodException | SecurityException e) {
        throw new RuntimeException("Unable to find UserCodeException.wrap", e);
      }
    }

    @Override
    public boolean isValid() {
      return true;
    }

    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:

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure a single consistent beam-sdks-java-core version on the classpath; remove duplicate/stale Beam jars.
2. Verify UserCodeException.class.getDeclaredMethods() contains wrap(Throwable); if not, rebuild/re-extract the jar.
3. Grant reflection permissions for org.apache.beam.* in the java.security.policy file, or disable the restrictive SecurityManager.
4. Fix shading config so the invoker factory and UserCodeException are relocated together (same prefix) or not relocated at all.

Example fix

// before: policy denies reflection
// grant { /* nothing for org.apache.beam */ };
// after (java.policy):
grant codeBase "file:/path/to/beam-sdks-java-core-2.60.0.jar" {
  permission java.lang.RuntimePermission "accessDeclaredMembers";
};

try {
  org.apache.beam.sdk.transforms.reflect.UserCodeException.class
      .getDeclaredMethod("wrap", Throwable.class);
} catch (NoSuchMethodException | SecurityException e) {
  throw new IllegalStateException("UserCodeException.wrap unavailable; check Beam jars/security policy", e);
}

try {
  DoFnInvoker invoker = DoFnInvoker.newInvoker(myDoFn);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("Unable to find UserCodeException.wrap")) {
    log.error("Beam jar mismatch or reflection denied; verify single beam-sdks-java-core version and policy grants", e);
    throw e;
  }
  throw e;
}

When it happens

Trigger: Loading ByteBuddyDoFnInvokerFactory (e.g. creating a DoFnInvoker via DoFnInvoker.newInvoker) when UserCodeException has no declared `wrap(Throwable)` method, or getDeclaredMethod throws SecurityException under an active SecurityManager that denies reflect access to org.apache.beam classes.

Common situations: Shaded/relocated copies of UserCodeException differing from the invoker factory; partial classpath with pruned Beam classes (ProGuard/R8 strip); sandboxed environments (application servers, Flink/Spark security profiles) with a SecurityManager blocking reflection on Beam internals.

Related errors

• cannot register Coder : method named 'of' with arguments of
• Failed to locate required method ${className}.${methodName}
• Failed to locate ProcessContinuation.stop()
• Failed to locate DefaultGetSize.validateSize()
• Unable to resolve class %s to use as Debezium connector.

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