apache/beam · error · IllegalArgumentException

No classpath elements found.

Error message

No classpath elements found.

What it means

If filesToStage is unset and classpath auto-detection yields an empty list, getDependencies throws IllegalArgumentException because an expansion service with no classpath resources cannot stage dependencies for workers.

Solutions

1. Set --filesToStage to an explicit list of jars to stage
2. Launch with a conventional classpath containing the service and its dependencies
3. If intentional (dependencies provided another way), supply an empty-string-safe config or pre-populate filesToStage via options
4. Verify detectClassPathResourcesToStage output with the same classloader in a diagnostic run

Example fix

// before
java --module-path mods ... ExpansionService  // detection finds nothing
// after
java -cp "libs/*" ExpansionService --filesToStage=libs/beam-sdks-java-expansion-service.jar

List<String> cp = PipelineResources.detectClassPathResourcesToStage(
    TransformProvider.class.getClassLoader(), options);
if (cp.isEmpty()) { options.as(PortablePipelineOptions.class)
    .setFilesToStage(Collections.singletonList(System.getProperty("java.class.path"))); }

try { deps = provider.getDependencies(request); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("No classpath")) { /* set filesToStage and retry */ } else throw e; }

When it happens

Trigger: Starting the expansion service with a classpath so minimal (e.g. single thin jar, jlink image) that PipelineResources.detectClassPathResourcesToStage finds nothing to stage.

Common situations: Modular/jlink runtime images; running from a REPL or tool that uses a custom classloader exposing no filesystem jars.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Cannot detect classpath: classloader is null (is it the…
• Conflicting registrations for
• A transform cannot be initiated using the provided config…
• AutoValue generated class not found
• cannot rehydrate Coder.

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

Appendix: source

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

            || options.as(ExpansionServiceOptions.class).getUseConfigDependenciesForManaged())) {
      List<String> updatedDependencies =
          config.getDependencies().get(transformUniqueID).stream()
              .map(dependency -> dependency.getPath())
              .collect(Collectors.toList());
      return updatedDependencies;
    }

    List<String> filesToStage = options.as(PortablePipelineOptions.class).getFilesToStage();

    if (filesToStage == null || filesToStage.isEmpty()) {
      ClassLoader classLoader = Environments.class.getClassLoader();
      if (classLoader == null) {
        throw new RuntimeException(
            "Cannot detect classpath: classloader is null (is it the bootstrap classloader?)");
      }
      filesToStage = PipelineResources.detectClassPathResourcesToStage(classLoader, options);
      if (filesToStage.isEmpty()) {
        throw new IllegalArgumentException("No classpath elements found.");
      }
    }
    return filesToStage;
  }
}

View on GitHub (pinned to 12126d8942)