juicedata/juicefs · error · IllegalArgumentException

random, backward, skip are mutually exclusive

Error message

random, backward, skip are mutually exclusive

What it means

checkArgs counts how many of -random, -backward and -skip are enabled for a -read run; more than one throws IllegalArgumentException "random, backward, skip are mutually exclusive". The three read modes cannot be combined in a single TestDFSIO run.

Source

Thrown at sdk/java/src/main/java/io/juicefs/bench/TestDFSIO.java:244

    createControlFile(fs, sizeInBytes, maps);
    if (compression != null) {
      LOG.info("compressionClass = " + compression);
    }
  }

  private void checkArgs() {
    if (!testType.equals("-read")) {
      if (random || backward || skip) {
        throw new IllegalArgumentException("random, backward, skip are only valid under read");
      }
    } else {
      boolean[] conds = {random, backward, skip};
      int trueCount = 0;
      for (boolean cond : conds) {
        if (cond) {
          trueCount++;
          if (trueCount > 1) {
            throw new IllegalArgumentException("random, backward, skip are mutually exclusive");
          }
        }
      }
    }
  }

  private void localRun(TestType testType) throws IOException {
    IOStatMapper ioer;
    switch (testType) {
      case TEST_TYPE_READ:
        ioer = new ReadMapper();
        break;
      case TEST_TYPE_WRITE:
        ioer = new WriteMapper();
        fs.delete(getDataDir(config), true);
        break;
      case TEST_TYPE_APPEND:
        ioer = new AppendMapper();

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Pick exactly one read mode per run: plain read, -random, -backward, or -skip.
2. Run multiple separate TestDFSIO invocations if you need results for several modes.
3. Add a pre-flight check in the benchmark script rejecting flag combinations.

Example fix

// before
TestDFSIO -read -random -backward -size 1GB
// after
TestDFSIO -read -random -size 1GB

long n = java.util.Arrays.stream(args).filter(a -> a.equals("-random")||a.equals("-backward")||a.equals("-skip")).count();
if (n > 1) throw new IllegalArgumentException("use only one of -random, -backward, -skip");

try {
  runTestDFSIO(args);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("mutually exclusive")) {
    throw new IllegalArgumentException("pick exactly one read mode", e);
  }
  throw e;
}

When it happens

Trigger: Running TestDFSIO -read with two or three of -random, -backward, -skip at once, e.g. 'TestDFSIO -read -random -backward'.

Common situations: Merging flags from two example command lines; a loop in a script appending all read-mode flags; confusion between 'backward' and 'skip' semantics.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• Unsupported ByteMultiple " + sMultiple
• wrong type
• random, backward, skip are only valid under read
• Cannot get file system.
• The directory item limit of " + controlDir + "

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