{"record":{"id":"afc156bba40387d5","repo":"apache/beam","slug":"could-not-find-class-s","errorCode":null,"errorMessage":"Could not find class: %s","messagePattern":"Could not find class: (.+?)","errorType":"exception","errorClass":"ClassNotFoundException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/InstanceBuilder.java","lineNumber":90,"sourceCode":"   * <p>If the name is a simple name (ie {@link Class#getSimpleName()}), then the package of the\n   * return type is added as a prefix.\n   *\n   * <p>The default class is the return type, specified in {@link #ofType}.\n   *\n   * <p>Modifies and returns the {@code InstanceBuilder} for chaining.\n   *\n   * @throws ClassNotFoundException if no class can be found by the given name\n   */\n  public InstanceBuilder<T> fromClassName(String name) throws ClassNotFoundException {\n    checkArgument(factoryClass == null, \"Class name may only be specified once\");\n    if (name.indexOf('.') == -1) {\n      name = type.getPackage().getName() + \".\" + name;\n    }\n\n    try {\n      factoryClass = Class.forName(name);\n    } catch (ClassNotFoundException e) {\n      throw new ClassNotFoundException(String.format(\"Could not find class: %s\", name), e);\n    }\n    return this;\n  }\n\n  /**\n   * Sets the factory class to use for instance construction.\n   *\n   * <p>Modifies and returns the {@code InstanceBuilder} for chaining.\n   */\n  public InstanceBuilder<T> fromClass(Class<?> factoryClass) {\n    this.factoryClass = factoryClass;\n    return this;\n  }\n\n  /**\n   * Sets the name of the factory method used to construct the instance.\n   *\n   * <p>The default, if no factory method was specified, is to look for a class constructor.","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/InstanceBuilder.java#L72-L108","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the fully-qualified class name spelling and package","Ensure the class is on the runtime classpath of the worker/job (check dependency scopes, shade plugin includes)","Check for class relocation (shading prefixes) and use the relocated name","Align library versions so the class exists in the version on the classpath"],"exampleFix":"// before\nnew InstanceBuilder().fromClassName(\"org.example.MyFactor\")\n// after\nnew InstanceBuilder().fromClassName(\"org.example.MyFactory\")","handlingStrategy":"validation","validationCode":"String name = \"org.example.MyFactory\";\ntry { Class.forName(name); } catch (ClassNotFoundException e) { throw new IllegalArgumentException(\"class not on classpath: \" + name); }","typeGuard":null,"tryCatchPattern":"try { builder.fromClassName(name).build(); } catch (ClassNotFoundException e) { log.error(\"check classpath and FQCN: {}\", name, e); }","preventionTips":["Verify fully-qualified names against the actual dependency version","Check worker classpath/deployment artifacts include the class","Watch for shading relocations changing package names"],"tags":["java","reflection","classpath","class-not-found"],"backgroundTag":"class-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}