apache/beam · error · IOException

Unable to load " + resourceId.path + " with " + classLoader…

Error message

Unable to load " + resourceId.path + " with " + classLoader + " URL " + classLoader.getResource(resourceId.path.substring(PREFIX.length()))

What it means

ClassLoaderFileSystem.open loads a classpath resource via classLoader.getResourceAsStream. When the resource is not found, it throws this IOException including the resource path, the classloader, and the URL resolution result, to diagnose which classloader failed to find the resource.

Solutions

Verify the resource exists on the runtime classpath (inspect the jar/target-classes) and that the path spelling and case match exactly
Pre-check classLoader.getResource(path) != null before opening
Ensure the resource is packaged: check build excludes/filters and that the containing jar is a runtime dependency
If the classloader hierarchy differs (containers, shading), load via Thread.currentThread().getContextClassLoader() instead

Defensive patterns

Strategy: try-catch

Validate before calling

String res = resourceId.path.substring("classpath://".length());
if (getClass().getClassLoader().getResource(res) == null) {
  throw new IOException("resource not on classpath: " + res);
}

Try / catch

try {
  return FileSystems.open(resourceId);
} catch (IOException e) {
  LOG.error("classpath resource missing: " + resourceId, e);
  throw e;
}

Prevention

Verify resource packaging (jar contents) in the build
Match path case and separators exactly as packaged
Test resource loading in the actual runtime environment with the same classloader setup

When it happens

Trigger: Opening a classpath:// resource whose path (after stripping the schema prefix) does not exist on the runtime classpath; resource present in a different classloader than getClass().getClassLoader().

Common situations: Typos or case mismatches in resource paths; resources in a dependency jar not on the runtime classpath; resources excluded by build packaging filters; different classloader hierarchy in app servers or shaded uber-jars.

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/io/ClassLoaderFileSystem.java:68

  @Override
  protected List<MatchResult> match(List<String> specs) throws IOException {
    throw new UnsupportedOperationException("Un-globbable filesystem.");
  }

  @Override
  protected WritableByteChannel create(
      ClassLoaderResourceId resourceId, CreateOptions createOptions) throws IOException {
    throw new UnsupportedOperationException("Read-only filesystem.");
  }

  @Override
  protected ReadableByteChannel open(ClassLoaderResourceId resourceId) throws IOException {
    ClassLoader classLoader = getClass().getClassLoader();
    InputStream inputStream =
        classLoader.getResourceAsStream(resourceId.path.substring(PREFIX.length()));
    if (inputStream == null) {

      throw new IOException(
          "Unable to load "
              + resourceId.path
              + " with "
              + classLoader
              + " URL "
              + classLoader.getResource(resourceId.path.substring(PREFIX.length())));
    }
    return Channels.newChannel(inputStream);
  }

  @Override
  protected void copy(
      List<ClassLoaderResourceId> srcResourceIds, List<ClassLoaderResourceId> destResourceIds)
      throws IOException {
    throw new UnsupportedOperationException("Read-only filesystem.");
  }

  @Override

View on GitHub (pinned to 12126d8942)