juicedata/juicefs · error · InvalidRequestException

Invalid parameter

Error message

Invalid parameter

What it means

isSuperUser() calls the native jfs_is_superuser with the current user and groups. A negative return signals the request itself was invalid (most commonly an invalid/uninitialized filesystem handle or bad parameter), and the code throws InvalidRequestException('Invalid parameter') instead of treating the user as non-super.

Source

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

    Pointer buf = null;
    while (r > size) {
      size = r;
      buf = Memory.allocate(Runtime.getRuntime(lib), size);
      r = lib.jfs_getGroups(name, user, buf, size);
    }
    if (r == 0) {
      return new HashSet<>(ugi.getGroups());
    }
    byte[] rBuf = new byte[r];
    buf.get(0, rBuf, 0, r);

    return new HashSet<>(Arrays.asList(new String(rBuf).split(",")));
  }

  private boolean isSuperUser() throws IOException {
    int r = lib.jfs_is_superuser(handle, user, String.join(",",  getGroups()));
    if (r < 0) {
      throw new InvalidRequestException("Invalid parameter");
    }
    return r == 1;
  }

  private boolean needCheckPermission() throws IOException {
    return rangerPermissionChecker != null && !isSuperGroupFileSystem && !isBackGroundTask && !isSuperUser() ;
  }

  private boolean checkPathAccess(Path path, FsAction action, String operation) throws IOException {
    return rangerPermissionChecker.checkPermission(path, false, null, null, action, operation, user, getGroups());
  }

  private boolean checkParentPathAccess(Path path, FsAction action, String operation) throws IOException {
    return rangerPermissionChecker.checkPermission(path, false, null, action, null, operation, user, getGroups());
  }

  private boolean checkAncestorAccess(Path path, FsAction action, String operation) throws IOException {
    return rangerPermissionChecker.checkPermission(path, false, action, null, null, operation, user, getGroups());

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Check earlier logs for a failed jfs_init or handle closure; re-create the FileSystem instance.
2. Verify the Hadoop user and group resolution (UGI) works on the node.
3. Ensure the juicefs-hadoop client version matches the native library version to avoid ABI mismatches.
4. If Ranger is enabled, confirm the Ranger config initialized correctly so the handle is valid.

Example fix

// before
FileSystem fs = FileSystem.get(uri, conf); // init failed earlier, handle <= 0 reused
fs.listStatus(path); // -> InvalidRequestException: Invalid parameter
// after
if (fs instanceof JuiceFileSystemImpl) ((JuiceFileSystemImpl) fs).getHandle() > 0; // or catch and re-init
fs.listStatus(path);

// ensure the FS initialized successfully and is open before permission-sensitive ops
if (fs instanceof JuiceFileSystemImpl) {
  ((JuiceFileSystemImpl) fs).getHandle(); // > 0 required; re-init otherwise
}

try { fs.listStatus(path); } catch (InvalidRequestException e) { if ("Invalid parameter".equals(e.getMessage())) { fs.close(); fs = FileSystem.get(uri, conf); fs.listStatus(path); } else throw e; }

When it happens

Trigger: Calling a permission-sensitive operation while needCheckPermission() is true (Ranger checker active, not super-group FS, not a background task) and jfs_is_superuser returns < 0 — e.g. the filesystem handle was closed/failed to initialize.

Common situations: The volume failed to initialize earlier but the FS object is still used; user/groups resolution fails so the native call gets unusable input; concurrent close of the filesystem while a permission check runs.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

• JuiceFS initialized failed for jfs://" + name
• wrong ranger config: %s
• illegal value for parameter 'ranger-rest-url': " + url
• illegal value for parameter 'ranger-service': " + serviceNam
• StubLoader load failed

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