juicedata/juicefs · error · IOException

wrong ranger config: %s

Error message

wrong ranger config: %s

What it means

The Ranger permission configuration is passed as a single string that must have exactly the form '<rest-url>?name=<service-name>'. The client splits on '?' and throws this IOException when the string does not contain exactly one '?' (i.e., not exactly two parts).

Source

Thrown at sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java:613

      return config;
    }
    int size = 0, r = 1 << 10;
    Pointer buf = null;
    while (r > size) {
      size = r;
      buf = Memory.allocate(Runtime.getRuntime(lib), size);
      r = lib.jfs_ranger_cfg(name, buf, size);
    }
    if (r == 0) {
      return null;
    }
    byte[] rBuf = new byte[r];
    buf.get(0, rBuf, 0, r);
    String cfgStr = new String(rBuf);
    // http://localhost:6080?name=service_name
    String[] split = cfgStr.split("\\?", -1);
    if (split.length != 2) {
      throw new IOException(String.format("wrong ranger config: %s", cfgStr));
    }
    String url = split[0];
    String serviceName = split[1].substring(5);
    if (!url.startsWith("http")) {
      throw new IOException("illegal value for parameter 'ranger-rest-url': " + url);
    }
    if (serviceName.isEmpty()) {
      throw new IOException("illegal value for parameter 'ranger-service': " + serviceName);
    }
    String pollIntervalMs = getConf(conf, "ranger-poll-interval-ms", "30000");
    return new RangerConfig(url, serviceName, Long.parseLong(pollIntervalMs));
  }

  public JuiceFileSystemImpl(boolean isSuperGroupFileSystem) {
    this.isSuperGroupFileSystem = isSuperGroupFileSystem;
  }

  private Set<String> getGroups() {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Set the config to exactly 'http://ranger-host:6080?name=<service_name>'.
2. Ensure there is exactly one '?' and the part after it starts with 'name='.
3. Remove any extra query parameters or trailing slashes from the URL.
4. Print the received config string in the error message (it is included) and compare character-by-character.

Example fix

// before
conf.set("juicefs.ranger-config", "http://ranger:6080"); // no ?name=...
// after
conf.set("juicefs.ranger-config", "http://ranger:6080?name=juicefs_service");

String cfg = conf.get("juicefs.ranger-config");
if (cfg != null && cfg.split("\\?", -1).length != 2) {
  throw new IllegalArgumentException("ranger config must be <url>?name=<service>: " + cfg);
}

try { fs = FileSystem.get(uri, conf); } catch (IOException e) { if (e.getMessage().startsWith("wrong ranger config")) { /* correct the config string */ } throw e; }

When it happens

Trigger: Setting the ranger config (e.g. juicefs.ranger-config or the value delivered via the config service) to a string without exactly one '?' separator, or with multiple '?' characters.

Common situations: Typing the Ranger REST URL without the '?name=service' suffix; pasting a URL that already contains query parameters; URL-encoding or extra whitespace breaking the split; forgetting the service_name portion.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• illegal value for parameter 'ranger-rest-url': " + url
• illegal value for parameter 'ranger-service': " + serviceNam
• name is required
• JuiceFS initialized failed for jfs://" + name
• Invalid parameter

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