apache/beam · error · IllegalArgumentException

No filesystem found for scheme

Error message

No filesystem found for scheme

What it means

FileSystems.getFileSystemInternal looks up a registered FileSystem by URL scheme; if no provider is registered for that scheme it throws IllegalArgumentException 'No filesystem found for scheme X'. All FileSystems operations (match, create, open, rename) go through this lookup.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileSystems.java:558

    // Here, we just need the scheme, which is so circumscribed as to be
    // very easy to extract with a regex.
    Matcher matcher = FILE_SCHEME_PATTERN.matcher(spec);

    if (!matcher.matches()) {
      return DEFAULT_SCHEME;
    } else {
      return matcher.group("scheme").toLowerCase();
    }
  }

  /** Internal method to get {@link FileSystem} for {@code scheme}. */
  @VisibleForTesting
  static FileSystem getFileSystemInternal(String scheme) {
    String lowerCaseScheme = scheme.toLowerCase();
    Map<String, FileSystem> schemeToFileSystem = SCHEME_TO_FILESYSTEM.get();
    FileSystem rval = schemeToFileSystem.get(lowerCaseScheme);
    if (rval == null) {
      throw new IllegalArgumentException("No filesystem found for scheme " + scheme);
    }
    return rval;
  }

  /** ******************************** METHODS FOR REGISTRATION ********************************* */

  /**
   * Sets the default configuration in workers.
   *
   * <p>It will be used in {@link FileSystemRegistrar FileSystemRegistrars} for all schemes.
   *
   * <p>Outside of workers where Beam FileSystem API is used (e.g. test methods, user code executed
   * during pipeline submission), consider use {@link #registerFileSystemsOnce} if initialize
   * FileSystem of supported schema is the main goal.
   */
  @Internal
  public static void setDefaultPipelineOptions(PipelineOptions options) {
    checkNotNull(options, "options cannot be null");

View on GitHub (pinned to 12126d8942)

Solutions

  1. Add the filesystem's Beam IO module dependency and ensure its FileSystem is registered (FileSystems.setDefaultPipelineOptions with proper options, or FileSystemRegistrar service loader)
  2. Verify the scheme spelling in your path
  3. Call FileSystems.getSchemeValidatedResource or pre-check with FileSystems.register... via SERVICE loader file META-INF/services/org.apache.beam.sdk.io.FileSystemRegistrar
  4. For local files ensure 'file' scheme handling is available (it is registered by core)

Example fix

// before
FileSystems.match("s3://my-bucket/data/*"); // IllegalArgumentException
// after
// add dependency: org.apache.beam:beam-sdks-java-io-amazon-web-services
S3Options s3Options = PipelineOptionsFactory.as(S3Options.class);
s3Options.setAwsRegion("us-east-1");
FileSystems.setDefaultPipelineOptions(s3Options);
FileSystems.match("s3://my-bucket/data/*");
Defensive patterns

Strategy: validation

Validate before calling

String scheme = RegisteredBarcode... ; // extract scheme from the path
String scheme = path.substring(0, path.indexOf("://"));
try {
  FileSystems.getFileSystemInternal(scheme); // @VisibleForTesting; or attempt a cheap match
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("Register a FileSystem for scheme: " + scheme, e);
}

Type guard

boolean isSupportedScheme(String path) {
  try {
    new URI(path).getScheme();
    return Set.of("file", "gs", "s3", "s3a", "abfs", "adl", "hdfs", "http", "https")
        .contains(new URI(path).getScheme());
  } catch (URISyntaxException e) { return false; }
}

Try / catch

try {
  return FileSystems.match(Collections.singletonList(spec));
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("No filesystem found for scheme")) {
    throw new IllegalStateException("Missing filesystem registration; add the Beam IO module", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling FileSystems.match/create/open/rename with a scheme (e.g. s3, gs, abfs) whose filesystem was never registered via FileSystems.setDefaultPipelineOptions + FileSystem registration, or using a misspelled/unsupported scheme.

Common situations: Using an S3 path in a pipeline without including beam-sdks-java-io-amazon-web-services dependency and registering S3FileSystem; running outside Dataflow/GCS where gs is not auto-registered; typos like 'filess://' or missing scheme ('/tmp/x' without a registered local scheme in some setups).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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