What causes "[BUG] Could not build FS URI" in juicedata/juicefs?

Fix the input URI: remove illegal characters from scheme/host and quote or percent-encode anything unusual.

juicedata/juicefs · error · DatasetOperationException

[BUG] Could not build FS URI

Error message

[BUG] Could not build FS URI

What it means

fileSystemURI builds the filesystem URI from the URI match map (scheme + host) using new URI(scheme, null, host, -1, "/", null, null). A URISyntaxException here indicates the matched scheme/host string is not a legal URI, which the loader treats as an internal invariant bug and wraps in DatasetOperationException prefixed with [BUG].

Source

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

      // 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();
    Registration.register(
            new URIPattern("jfs:/*path"),
            new URIPattern("jfs:/*path/:namespace/:dataset"),
            builder);
  }

  private static URI fileSystemURI(Map<String, String> match) {
    try {
      return new URI(match.get(URIPattern.SCHEME), null,
              match.get(URIPattern.HOST), -1, "/", null, null);
    } catch (URISyntaxException ex) {
      throw new DatasetOperationException("[BUG] Could not build FS URI", ex);
    }
  }
}

View on GitHub (pinned to c9a67b23e8)

Solutions

Fix the input URI: remove illegal characters from scheme/host and quote or percent-encode anything unusual.
Log/inspect the URISyntaxException cause (it names the offending index and reason) and correct the URI accordingly.
If it occurs with a well-formed URI, check for a version mismatch between KiteDataLoader and the URIPattern groups (host capturing the wrong text) and pin matching versions.

Example fix

// before
DatasetRepository r = loader.getFromOptions(match); // match host = "my vol"
// after
DatasetRepository r = loader.getFromOptions(match); // uri = jfs://myvol/path (no spaces in host)

Defensive patterns

Strategy: validation

Validate before calling

URI u = java.net.URI.create(uriString); // throws IllegalArgumentException on illegal chars
if (u.getHost() == null || !u.getHost().matches("[A-Za-z0-9.\\-]+")) {
  throw new IllegalArgumentException("illegal host in URI: " + uriString);
}

Try / catch

try {
  DatasetRepository repo = loader.getFromOptions(match);
} catch (DatasetOperationException e) {
  throw new IllegalArgumentException("malformed jfs URI (host/scheme): " + e.getCause().getMessage(), e);
}

Prevention

Build URIs with URI.create or the multi-arg URI constructor rather than string concat.
Reject URIs with spaces or brackets in the authority at input validation.
Keep KiteDataLoader and URIPattern versions aligned.

When it happens

Trigger: Calling getFromOptions with a jfs: URI whose matched scheme or host group contains characters illegal in a URI authority (spaces, brackets, control chars), producing URISyntaxException inside fileSystemURI.

Common situations: Hand-typing a malformed URI like 'jfs://my vol/path' or 'jfs://[weird]/x' into a Kite-based tool; a pattern upgrade changing URIPattern group capture so a path fragment lands in the HOST slot.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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