{"record":{"id":"f6267fca6d9fb538","repo":"apache/beam","slug":"cannot-detect-classpath-classloader-is-null-is-it-the","errorCode":null,"errorMessage":"Cannot detect classpath: classloader is null (is it the bootstrap classloader?)","messagePattern":"Cannot detect classpath: classloader is null \\(is it the bootstrap classloader\\?\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/TransformProvider.java","lineNumber":209,"sourceCode":"    // option\n    // is specified.\n    if (transformUniqueID != null\n        && config.getDependencies().containsKey(transformUniqueID)\n        && (!isManagedExpansion\n            || options.as(ExpansionServiceOptions.class).getUseConfigDependenciesForManaged())) {\n      List<String> updatedDependencies =\n          config.getDependencies().get(transformUniqueID).stream()\n              .map(dependency -> dependency.getPath())\n              .collect(Collectors.toList());\n      return updatedDependencies;\n    }\n\n    List<String> filesToStage = options.as(PortablePipelineOptions.class).getFilesToStage();\n\n    if (filesToStage == null || filesToStage.isEmpty()) {\n      ClassLoader classLoader = Environments.class.getClassLoader();\n      if (classLoader == null) {\n        throw new RuntimeException(\n            \"Cannot detect classpath: classloader is null (is it the bootstrap classloader?)\");\n      }\n      filesToStage = PipelineResources.detectClassPathResourcesToStage(classLoader, options);\n      if (filesToStage.isEmpty()) {\n        throw new IllegalArgumentException(\"No classpath elements found.\");\n      }\n    }\n    return filesToStage;\n  }\n}\n","sourceCodeStart":191,"sourceCodeEnd":220,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/TransformProvider.java#L191-L220","documentation":"When no files-to-stage option is provided, getDependencies auto-detects the classpath using the classloader of the Environments class. Under the bootstrap classloader that getter returns null, so the service cannot detect the classpath and throws.","triggerScenarios":"Running the expansion service on the boot classloader (e.g. -Xbootclasspath or unusual launcher) while PortablePipelineOptions.filesToStage is unset, forcing classpath auto-detection.","commonSituations":"Embedding the expansion service in a stripped-down JVM/container launch script; launching via a mechanism that bypasses the system classloader.","solutions":["Explicitly set --filesToStage (PortablePipelineOptions) so auto-detection is skipped","Launch the expansion service with a normal application classloader (java -jar / standard classpath)","If embedding, pass your own classloader context or precompute classpath resources","Check the launch command for -Xbootclasspath or custom launcher flags and remove them"],"exampleFix":"// before\njava -Xbootclasspath/a:beam.jar ... ExpansionServiceServer --port=8097\n// after\njava -cp beam.jar:libs/* org.apache.beam.sdk.expansion.service.ExpansionService --port=8097 \\\n  --filesToStage=/libs/*","handlingStrategy":"fallback","validationCode":"if (options.as(PortablePipelineOptions.class).getFilesToStage() == null\n    && Environments.class.getClassLoader() == null) {\n  options.as(PortablePipelineOptions.class).setFilesToStage(computeExplicitStageList());\n}","typeGuard":null,"tryCatchPattern":"try { deps = provider.getDependencies(request); } catch (RuntimeException e) { if (e.getMessage().contains(\"classloader is null\")) setFilesToStageExplicitly(); throw e; }","preventionTips":["Always pass --filesToStage in non-standard launchers","Avoid -Xbootclasspath for the service","Verify classloader with Environments.class.getClassLoader() != null in smoke tests"],"tags":["java","classpath","expansion-service"],"backgroundTag":"missing-env-var","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}