{"record":{"id":"33d2060d113d2602","repo":"apache/beam","slug":"scheme-s-has-conflicting-filesystems-s","errorCode":null,"errorMessage":"Scheme: [%s] has conflicting filesystems: [%s]","messagePattern":"Scheme: \\[(.+?)\\] has conflicting filesystems: \\[(.+?)\\]","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileSystems.java","lineNumber":640,"sourceCode":"  static Map<String, FileSystem> verifySchemesAreUnique(\n      PipelineOptions options, Set<FileSystemRegistrar> registrars) {\n    Multimap<String, FileSystem> fileSystemsBySchemes =\n        TreeMultimap.create(Ordering.<String>natural(), Ordering.arbitrary());\n\n    for (FileSystemRegistrar registrar : registrars) {\n      for (FileSystem fileSystem : registrar.fromOptions(options)) {\n        fileSystemsBySchemes.put(fileSystem.getScheme(), fileSystem);\n      }\n    }\n    for (Entry<String, Collection<FileSystem>> entry : fileSystemsBySchemes.asMap().entrySet()) {\n      if (entry.getValue().size() > 1) {\n        String conflictingFileSystems =\n            Joiner.on(\", \")\n                .join(\n                    FluentIterable.from(entry.getValue())\n                        .transform(input -> input.getClass().getName())\n                        .toSortedList(Ordering.natural()));\n        throw new IllegalStateException(\n            String.format(\n                \"Scheme: [%s] has conflicting filesystems: [%s]\",\n                entry.getKey(), conflictingFileSystems));\n      }\n    }\n\n    ImmutableMap.Builder<String, FileSystem> schemeToFileSystem = ImmutableMap.builder();\n    for (Entry<String, FileSystem> entry : fileSystemsBySchemes.entries()) {\n      schemeToFileSystem.put(entry.getKey(), entry.getValue());\n    }\n    return schemeToFileSystem.build();\n  }\n\n  /**\n   * Returns a new {@link ResourceId} that represents the named resource of a type corresponding to\n   * the resource type.\n   *\n   * <p>The supplied {@code singleResourceSpec} is expected to be in a proper format, including any","sourceCodeStart":622,"sourceCodeEnd":658,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileSystems.java#L622-L658","documentation":"FileSystems.verifySchemesAreUnique detects two or more different FileSystem implementations registered for the same URL scheme and throws IllegalStateException listing the conflicting class names. This prevents ambiguous filesystem routing when multiple providers claim one scheme.","triggerScenarios":"Setting default pipeline options (FileSystems.setDefaultPipelineOptions) when the classpath contains multiple FileSystemRegistrar service-loader entries producing filesystems with the same scheme — typically duplicate or incompatible Beam IO jars on the classpath.","commonSituations":"Shading multiple Beam versions into one fat jar; including both a legacy and new filesystem provider for the same scheme; classpath pollution in Spark/Flink/Beam worker images.","solutions":["Run mvn dependency:tree / gradle dependencies and exclude duplicate Beam IO modules providing the same scheme","Align all org.apache.beam artifacts to one version","Check META-INF/services/org.apache.beam.software... FileSystemRegistrar registrations inside bundled jars and remove the conflicting jar","In worker images, clean up stale Beam jars (e.g. in Spark/Flink lib dirs)"],"exampleFix":"// before (pom.xml)\n<dependency>org.apache.beam:beam-sdks-java-io-google-cloud-platform:2.40.0</dependency>\n<dependency>org.apache.beam:beam-sdks-java-io-google-cloud-platform:2.50.0</dependency>\n// after\n<dependency>org.apache.beam:beam-sdks-java-io-google-cloud-platform:2.50.0</dependency>\n<!-- single version, duplicates excluded -->","handlingStrategy":"validation","validationCode":"// Check the classpath for duplicate Beam IO jars before launching\nSet<String> seen = new HashSet<>();\nfor (FileSystemRegistrar r : ServiceLoader.load(FileSystemRegistrar.class)) {\n  for (String s : r.schemes()) {\n    if (!seen.add(s)) throw new IllegalStateException(\"Duplicate scheme: \" + s);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  FileSystems.setDefaultPipelineOptions(options);\n} catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"has conflicting filesystems\")) {\n    throw new IllegalStateException(\"Duplicate Beam IO jars on classpath; run dependency:tree\", e);\n  }\n  throw e;\n}","preventionTips":["Use maven-enforcer dependencyConvergence to pin one Beam version","Audit fat jars with duplicate class/package checks","Keep worker images free of stale Beam jars in shared lib dirs","Avoid shading Beam with multiple versions merged together"],"tags":["java","apache-beam","filesystem","classpath","conflict"],"backgroundTag":"conflicting-config-options","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"}