juicedata/juicefs · error · IOException

wrong ranger config

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).

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': " +…
• bucket name required
• Can't read default config file
• Cannot load default config

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

Appendix: 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)