juicedata/juicefs · error · IllegalArgumentException

random, backward, skip are only valid under read

Error message

random, backward, skip are only valid under read

What it means

TestDFSIO.checkArgs enforces that the modifiers -random, -backward and -skip are only combined with the -read operation; if any of them is set while testType != "-read", it throws IllegalArgumentException with this message. It is a semantic argument-combination check run from init.

Source

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

    LOG.info("threads = " + threadsPerMap);
    LOG.info("files = " + filesPerThread);
    LOG.info("randomBytes = " + randomBytes);
    LOG.info("fileSize (MB) = " + TestDFSIO.toMB(sizeInBytes));
    LOG.info("bufferSize = " + bufferSize);
    if (skipSizeInBytes > 0)
      LOG.info("skipSize = " + skipSize);
    LOG.info("baseDir = " + baseDir);

    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) {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Remove -random/-backward/-skip when running -write, -append, -clean or -truncate.
2. Switch the operation to -read if you intended randomized/backward/skip reads.
3. Validate the flag/op combination in the wrapper script before submitting the job.

Example fix

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

boolean hasReadModifier = java.util.Arrays.stream(args).anyMatch(a -> a.equals("-random")||a.equals("-backward")||a.equals("-skip"));
if (hasReadModifier && !java.util.Arrays.asList(args).contains("-read")) {
  throw new IllegalArgumentException("-random/-backward/-skip require -read");
}

try {
  runTestDFSIO(args);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("only valid under read")) {
    throw new IllegalArgumentException("drop -random/-backward/-skip or switch op to -read", e);
  }
  throw e;
}

When it happens

Trigger: Running TestDFSIO with an operation other than -read together with any of -random, -backward or -skip, e.g. 'TestDFSIO -write -random -size 1GB'.

Common situations: Reusing a read benchmark script as a template and only changing the op to -write/-append while leaving -random in place; misreading docs that these flags apply to reads only.

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 mutually exclusive
• 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/b0e672bbb0bcb242. Report an issue: GitHub.