juicedata/juicefs · error · IOException

illegal value for parameter 'ranger-rest-url': " + url

Error message

illegal value for parameter 'ranger-rest-url': " + url

What it means

After splitting the ranger config string, the URL portion must be an HTTP(S) endpoint. If it does not start with 'http', the client rejects it because the Ranger permission checker polls a REST API and cannot use any other scheme.

Source

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

      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() {
    String groupsFile = getConf(getConf(), "groups", null);
    if (isEmpty(groupsFile)) {
      return new HashSet<>(ugi.getGroups());
    }

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Prefix the URL with http:// or https:// explicitly.
  2. Verify no placeholder text or whitespace precedes 'http' in the config value.
  3. Test the URL with curl from the client node to confirm the Ranger admin REST endpoint responds.

Example fix

// before
conf.set("juicefs.ranger-config", "ranger.internal:6080?name=svc");
// after
conf.set("juicefs.ranger-config", "https://ranger.internal:6080?name=svc");
Defensive patterns

Strategy: validation

Validate before calling

String cfg = conf.get("juicefs.ranger-config");
String url = cfg == null ? null : cfg.split("\\?", -1)[0];
if (url == null || !url.startsWith("http")) {
  throw new IllegalArgumentException("ranger-rest-url must start with http(s): " + url);
}

Try / catch

try { fs = FileSystem.get(uri, conf); } catch (IOException e) { if (e.getMessage().startsWith("illegal value for parameter 'ranger-rest-url'")) { /* add http:// or https:// */ } throw e; }

Prevention

When it happens

Trigger: The part of the ranger config before '?' does not begin with 'http', e.g. 'ranger-host:6080?name=svc' or 'httpsx://...' (typo).

Common situations: Omitting the scheme when writing the Ranger URL; using https:// but a typo removed characters; environment-specific placeholder (e.g. RANGER_URL) left unsubstituted.

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/8579ee3b2ec35a98. Report an issue: GitHub.