juicedata/juicefs · error · DatasetIOException

Could not get a FileSystem

Error message

Could not get a FileSystem

What it means

getFromOptions tries to obtain a Hadoop FileSystem for the URI matched from user options via FileSystem.get(fileSystemURI(match), conf). If that call throws IOException (the Hadoop client cannot instantiate the filesystem for the scheme/host), the loader wraps it in Kite's DatasetIOException with this message. It signals the filesystem plugin/config, not the dataset, is broken.

Source

Thrown at sdk/java/src/main/java/io/juicefs/KiteDataLoader.java:45

import java.net.URI;
import java.net.URISyntaxException;
import java.util.Map;

public class KiteDataLoader implements Loadable {
  private static class URIBuilder implements OptionBuilder<DatasetRepository> {

    @Override
    public DatasetRepository getFromOptions(Map<String, String> match) {
      String path = match.get("path");
      final Path root = (path == null || path.isEmpty()) ?
              new Path("/") : new Path("/", path);

      Configuration conf = DefaultConfiguration.get();
      FileSystem fs;
      try {
        fs = FileSystem.get(fileSystemURI(match), conf);
      } catch (IOException e) {
        throw new DatasetIOException("Could not get a FileSystem", e);
      }
      return new FileSystemDatasetRepository.Builder()
              .configuration(new Configuration(conf)) // make a modifiable copy
              .rootDirectory(fs.makeQualified(root))
              .build();
    }
  }

  @Override
  public void load() {
    try {
      // load hdfs-site.xml by loading HdfsConfiguration
      FileSystem.getLocal(DefaultConfiguration.get());
    } catch (IOException e) {
      throw new DatasetIOException("Cannot load default config", e);
    }

    OptionBuilder<DatasetRepository> builder = new URIBuilder();

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Add the JuiceFS Hadoop client jar to the application classpath (or HADOOP_CLASSPATH) so the jfs:// scheme resolves.
2. Set fs.jfs.impl=io.juicefs.JuiceFileSystem (and the redis/meta URL config) in core-site.xml or the Configuration used.
3. Check the wrapped IOException cause for the real reason (e.g. NoClassDefFoundError, config load failure) and fix that.
4. Verify the URI host/scheme matched by URIPattern("jfs:/*path") is well-formed; fix the input URI string.

Example fix

// before: jfs://myvol/path with no plugin registered -> DatasetIOException
// after (core-site.xml)
<property><name>fs.jfs.impl</name><value>io.juicefs.JuiceFileSystem</value></property>
<property><name>juicefs.meta</name><value>redis://127.0.0.1:6379/1</value></property>

// before calling the loader
Class<?> cls = Class.forName("io.juicefs.JuiceFileSystem");
if (conf.get("fs.jfs.impl") == null) throw new IllegalStateException("fs.jfs.impl not set");
URI u = java.net.URI.create(inputUri); // throws early on malformed input
if (!"jfs".equals(u.getScheme())) throw new IllegalArgumentException("expected jfs URI");

try {
  DatasetRepository repo = loader.getFromOptions(match);
} catch (DatasetIOException e) {
  LOG.error("FileSystem init failed; check fs.jfs.impl and classpath", e.getCause());
  throw new IllegalStateException("jfs filesystem unavailable: " + e.getCause().getMessage(), e);
}

When it happens

Trigger: Calling KiteDataLoader.getFromOptions (via the Kite URIBuilder/DatasetRepository path) with a jfs: URI whose scheme has no registered Hadoop FileSystem implementation on the classpath, or when the Configuration fails to initialize plugins for that scheme.

Common situations: Running a Kite-based job (e.g. Cloudera Navigator/Spark integration) against JuiceFS without juicefs-hadoop jar on the classpath; fs.jfs.impl / fs.AbstractFileSystem.jfs.impl keys missing from core-site.xml; corrupted or unreadable Hadoop config files so DefaultConfiguration.get() returns a broken Configuration.

Related errors

• name is required
• Cannot load default config
• Cannot get file system.
• Cannot create file system.
• Invalid start or len parameter

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/0ce7734931b8de0a. Report an issue: GitHub.