juicedata/juicefs · error · IOException

RangerPermissionChecker for volume: " + volName + " is alrea

Error message

RangerPermissionChecker for volume: " + volName + " is already created, but no running instance found.

What it means

RangerPermissionChecker.acquire enforces that at most one permission checker exists per volume. If a checker was previously created (present in pcs) but no running instance is registered in runningInstance (e.g. a previous release() path failed or state was corrupted), acquire throws this IOException instead of creating a duplicate.

Source

Thrown at sdk/java/src/main/java/io/juicefs/permission/RangerPermissionChecker.java:83

  public RangerPermissionChecker(FileSystem superGroupFileSystem, RangerConfig config) {
    this.superGroupFileSystem = superGroupFileSystem;
    rangerPlugin = new RangerJfsPlugin(superGroupFileSystem, config.getServiceName(), config.getRangerRestUrl(), config.getPollIntervalMs());
    rangerPlugin.getConfig().set("ranger.plugin.hdfs.service.name", config.getServiceName());
    rangerPlugin.getConfig().set("ranger.plugin.hdfs.policy.rest.url", config.getRangerRestUrl());
    // for test use
    if (config.getImpl() != null) {
      rangerPlugin.getConfig().set("ranger.plugin.hdfs.policy.source.impl", config.getImpl());
    }
    rangerPlugin.getConfig().setIsFallbackSupported(true);
    rangerPlugin.init();
  }

  public static RangerPermissionChecker acquire(String volName, long handle, FileSystem superGroupFileSystem, RangerConfig config) throws IOException {
    synchronized (runningInstance) {
      if (!runningInstance.containsKey(volName)) {
        if (pcs.containsKey(volName)) {
          throw new IOException("RangerPermissionChecker for volume: " + volName + " is already created, but no running instance found.");
        }
        RangerPermissionChecker pc = new RangerPermissionChecker(superGroupFileSystem, config);
        pcs.put(volName, pc);
        Set<Long> handles = new HashSet<>();
        handles.add(handle);
        runningInstance.put(volName, handles);
        return pc;
      } else {
        RangerPermissionChecker pc = pcs.get(volName);
        if (pc == null) {
          throw new IOException("RangerPermissionChecker for volume: " + volName + " is already created, but no instance found.");
        }
        runningInstance.get(volName).add(handle);
        return pc;
      }
    }
  }

View on GitHub (pinned to c9a67b23e8)

Solutions

Ensure release() is called for every handle acquired so pcs/runningInstance stay in sync
Restart the client JVM process to clear stale static state
Inspect release logic for exceptions that skip pcs.remove(volName)
Guard against re-acquiring after all handles released until the cleanup path is fixed

Defensive patterns

Strategy: try-catch

Type guard

boolean checkerStale(String vol) {
  // via reflection over internal state, or track client-side usage
  return acquiredVolumes.getOrDefault(vol, 0) == 0;
}

Try / catch

try {
  pc = RangerPermissionChecker.acquire(volName, handle, fs, config);
} catch (IOException e) {
  if (e.getMessage().contains("is already created, but no running instance found")) {
    LOG.error("Stale checker state; restart client JVM and ensure release() is always called", e);
  } else throw e;
}

Prevention

Always call release() in a finally block for every acquired handle
Do not manipulate checker lifecycle maps concurrently
Restart the client if acquire/release paths ever throw

When it happens

Trigger: Calling RangerPermissionChecker.acquire for a volName that exists in pcs but not in runningInstance — i.e. an earlier acquire created the checker, all handles were removed but pcs entry was never cleaned, or internal state desynchronized between the two maps.

Common situations: A release() path threw before removing the pcs entry; multiple FileSystem clients in one JVM across restart cycles; concurrent lifecycle bugs leaving pcs populated while runningInstance is empty.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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