bazelbuild/bazel · error · IllegalStateException

Unsupported JUnit Runner API version ${JUNIT_API_VERSION_PRO

Error message

Unsupported JUnit Runner API version ${JUNIT_API_VERSION_PROPERTY}=${junitApiVersion} (must be \"1\")

What it means

Thrown by JUnit4Config.getJUnitRunnerApiVersion() when the system property com.google.testing.junit.runner.apiVersion does not parse to the integer 1. The junitrunner jar and the Bazel test harness negotiate a contract via this version, and this build of the runner only supports API version 1. The property defaults to "1", so hitting this error means something explicitly set it to another value or to a non-numeric string.

Source

Thrown at src/java_tools/junitrunner/java/com/google/testing/junit/runner/junit4/JUnit4Config.java:110

  }

  /**
   * Gets the version of the JUnit Runner that the test is expecting.
   * Some features may be enabled or disabled based on this value.
   *
   * @return api version
   * @throws IllegalStateException if the API version is unsupported.
   */
  public int getJUnitRunnerApiVersion() {
    int apiVersion = 0;
    try {
      apiVersion = Integer.parseInt(junitApiVersion);
    } catch (NumberFormatException e) {
      // ignore; handled below
    }

    if (apiVersion != 1) {
      throw new IllegalStateException(
          "Unsupported JUnit Runner API version " + JUNIT_API_VERSION_PROPERTY + "="
          + junitApiVersion + " (must be \\\"1\\\")");
    }
    return apiVersion;
  }

  /**
   * Returns the value of the {@code test_runner_fail_fast} option, or <code>false<code/> if
   * it was not specified.
   */
  boolean getTestRunnerFailFast() {
    return testRunnerFailFast;
  }

  /**
   * Returns a regular expression representing an inclusive filter.
   * Only test descriptions that match this regular expression should be run.
   */

View on GitHub (pinned to e6e199d060)

Solutions

Remove the -Dcom.google.testing.junit.runner.apiVersion=... flag so the default "1" applies.
If you must set it, set it to exactly 1: -Dcom.google.testing.junit.runner.apiVersion=1.
Align the junitrunner jar with the Bazel version running the test (rebuild/re-pin java_tools to the matching Bazel release).
If you wrap the runner programmatically, validate the property before constructing JUnit4Runner.

Example fix

# before
java -Dcom.google.testing.junit.runner.apiVersion=2 com.google.testing.junit.runner.junit4.JUnit4Runner ...
# after
java -Dcom.google.testing.junit.runner.apiVersion=1 com.google.testing.junit.runner.junit4.JUnit4Runner ...

Defensive patterns

Strategy: validation

Validate before calling

// before launching the runner
String v = System.getProperty("com.google.testing.junit.runner.apiVersion", "1").trim();
if (!"1".equals(v)) {
  throw new IllegalArgumentException(
      "Refusing to run with apiVersion=" + v + "; only 1 is supported");
}

Try / catch

try {
  runner.run();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("JUnit Runner API version")) {
    // report config problem distinctly from test failures
  } else { throw e; }
}

Prevention

Never copy -Dcom.google.testing.junit.runner.apiVersion between Bazel versions.
Run tests via bazel test so the harness supplies a consistent property value.
Assert in CI that manually launched runner commands omit the apiVersion flag.

When it happens

Trigger: Calling new JUnit4Runner(...) or RunPaths.run() with -Dcom.google.testing.junit.runner.apiVersion=2, =0, ="" or any non-numeric value; also embedding an older/newer junitrunner jar that expects a different version while the harness injects its own value.

Common situations: Running the JUnit4Runner main class by hand (outside bazel test) with copied JVM flags from a different Bazel version; mixing a Bazel-deployed runner with a locally built junitrunner jar; CI scripts that pass a stale -D flag.

Related errors

AI-assisted analysis of bazelbuild/bazel@e6e199d060 (2026-08-14). Data as JSON: /api/errors/98622f53d5bbaeef. Report an issue: GitHub.