juicedata/juicefs · error · IOException

illegal value for parameter 'ranger-service': " + serviceNam

Error message

illegal value for parameter 'ranger-service': " + serviceName

What it means

The ranger config's query part must be 'name=<service_name>'; the code strips the fixed 5-character 'name=' prefix and requires the remaining service name to be non-empty. An empty service name would make Ranger policy lookups meaningless, so initialization throws this IOException.

Source

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

    }
    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());
    }

    int size = 0, r = 1 << 10;
    Pointer buf = null;
    while (r > size) {

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Set the full config to 'http://<ranger-host>:6080?name=<existing-service-name>'.
  2. Confirm the query part literally starts with 'name=' (not 'service=' or 'servicename=').
  3. Create the corresponding service in the Ranger admin console if it does not exist, then use that exact name.

Example fix

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

Strategy: validation

Validate before calling

String cfg = conf.get("juicefs.ranger-config");
if (cfg != null) {
  String q = cfg.split("\\?", -1).length == 2 ? cfg.split("\\?", -1)[1] : "";
  String svc = q.startsWith("name=") ? q.substring(5) : null;
  if (svc == null || svc.isEmpty()) {
    throw new IllegalArgumentException("ranger config must end with ?name=<non-empty service>");
  }
}

Try / catch

try { fs = FileSystem.get(uri, conf); } catch (IOException e) { if (e.getMessage().startsWith("illegal value for parameter 'ranger-service'")) { /* set a real service name */ } throw e; }

Prevention

When it happens

Trigger: Ranger config like 'http://ranger:6080?name=' (nothing after 'name='), or the part after '?' not starting with 'name=' so the substring(5) yields an empty/wrong string.

Common situations: Leaving the service_name blank in the config template; writing '?service=svc' instead of '?name=svc' so substring(5) produces the wrong/empty value; the Ranger service was never created so admins omitted the name.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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