apache/beam · error · java.lang.IllegalArgumentException

Could not find class

Error message

Could not find class 

What it means

getTransform reflectively loads and instantiates the requested class (Class.forName / constructors / static methods) from the allow-listed class name. If the class cannot be loaded (ClassNotFoundException) it throws IllegalArgumentException('Could not find class <className>'). The class named in the JavaClassLookupPayload is not on the expansion service classpath.

Source

Thrown at sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/JavaClassLookupTransformProvider.java:132

        Constructor<PTransform<InputT, OutputT>> constructor =
            findMappingConstructor(constructors, payload);
        Object[] parameterValues =
            getParameterValues(
                constructor.getParameters(),
                constructorRow,
                constructor.getGenericParameterTypes());
        transform = (PTransform<PInput, POutput>) constructor.newInstance(parameterValues);
      } else {
        Method[] methods = transformClass.getMethods();
        Method method = findMappingConstructorMethod(methods, payload, allowlistClass);
        Object[] parameterValues =
            getParameterValues(
                method.getParameters(), constructorRow, method.getGenericParameterTypes());
        transform = (PTransform<PInput, POutput>) method.invoke(null /* static */, parameterValues);
      }
      return applyBuilderMethods(transform, payload, allowlistClass);
    } catch (ClassNotFoundException e) {
      throw new IllegalArgumentException("Could not find class " + className, e);
    } catch (InstantiationException
        | IllegalArgumentException
        | IllegalAccessException
        | InvocationTargetException e) {
      throw new IllegalArgumentException("Could not instantiate class " + className, e);
    }
  }

  @SuppressWarnings("assignment")
  private PTransform<PInput, POutput> applyBuilderMethods(
      PTransform<PInput, POutput> transform,
      JavaClassLookupPayload payload,
      AllowedClass allowListClass) {
    for (BuilderMethod builderMethod : payload.getBuilderMethodsList()) {
      Method method = getMethod(transform, builderMethod, allowListClass);
      try {
        Row builderMethodRow = decodeRow(builderMethod.getSchema(), builderMethod.getPayload());
        transform =

View on GitHub (pinned to 12126d8942)

Solutions

1. Add the jar containing the class to the expansion service classpath and restart
2. Verify the fully-qualified class name in the request matches the deployed class (package + name)
3. Rebuild/redploy clients after class renames so payload class names are current
4. Prefer registered SchemaTransforms over raw JavaClassLookup to avoid classpath coupling

Example fix

// before
java -cp expansion-service.jar ...ExpansionService  // MyTransform missing
// after
java -cp expansion-service.jar:my-transforms.jar ...ExpansionService

try { Class.forName("com.example.MyTransform", false, expansionServiceClassloader); } catch (ClassNotFoundException e) { throw new IllegalStateException("Class not on expansion service classpath"); }

try { expanded = service.expand(request); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Could not find class ")) { /* add jar / fix FQCN */ } throw e; }

When it happens

Trigger: Requesting JavaClassLookup expansion for a class that is not on the expansion service's classpath, or whose name is mistyped (wrong package/class spelling).

Common situations: Expansion service launched without the jar containing the target transform class; refactoring renamed/moved the class while clients still send old names; using the default (non-cross-language-safe) class lookup with user classes absent from the service image.

Related errors

• Failed to locate required method ${className}.${methodName}
• Failed to locate ProcessContinuation.stop()
• Failed to locate DefaultGetSize.validateSize()
• Unable to find UserCodeException.wrap
• Could not find class: %s

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