apache/beam · error · ClassNotFoundException

Could not find class: %s

Error message

Could not find class: %s

What it means

InstanceBuilder.fromClassName() wraps ClassNotFoundException thrown by Class.forName(name) with a message 'Could not find class: %s'. It is used to build instances from fully-qualified class names (e.g. from pipeline options or serialized specs), so a typo'd or missing class name fails here.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/InstanceBuilder.java:90

   * <p>If the name is a simple name (ie {@link Class#getSimpleName()}), then the package of the
   * return type is added as a prefix.
   *
   * <p>The default class is the return type, specified in {@link #ofType}.
   *
   * <p>Modifies and returns the {@code InstanceBuilder} for chaining.
   *
   * @throws ClassNotFoundException if no class can be found by the given name
   */
  public InstanceBuilder<T> fromClassName(String name) throws ClassNotFoundException {
    checkArgument(factoryClass == null, "Class name may only be specified once");
    if (name.indexOf('.') == -1) {
      name = type.getPackage().getName() + "." + name;
    }

    try {
      factoryClass = Class.forName(name);
    } catch (ClassNotFoundException e) {
      throw new ClassNotFoundException(String.format("Could not find class: %s", name), e);
    }
    return this;
  }

  /**
   * Sets the factory class to use for instance construction.
   *
   * <p>Modifies and returns the {@code InstanceBuilder} for chaining.
   */
  public InstanceBuilder<T> fromClass(Class<?> factoryClass) {
    this.factoryClass = factoryClass;
    return this;
  }

  /**
   * Sets the name of the factory method used to construct the instance.
   *
   * <p>The default, if no factory method was specified, is to look for a class constructor.

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify the fully-qualified class name spelling and package
2. Ensure the class is on the runtime classpath of the worker/job (check dependency scopes, shade plugin includes)
3. Check for class relocation (shading prefixes) and use the relocated name
4. Align library versions so the class exists in the version on the classpath

Example fix

// before
new InstanceBuilder().fromClassName("org.example.MyFactor")
// after
new InstanceBuilder().fromClassName("org.example.MyFactory")

String name = "org.example.MyFactory";
try { Class.forName(name); } catch (ClassNotFoundException e) { throw new IllegalArgumentException("class not on classpath: " + name); }

try { builder.fromClassName(name).build(); } catch (ClassNotFoundException e) { log.error("check classpath and FQCN: {}", name, e); }

When it happens

Trigger: Passing a class name to InstanceBuilder.fromClassName where the class is not on the classpath, the package prefix is wrong, or the name is misspelled.

Common situations: Misspelled fully-qualified class name in configuration; class exists in the SDK but not on the worker's classpath; fat-jar/shading removed or relocated the class; version change renamed the class.

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

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