{"record":{"id":"98622f53d5bbaeef","repo":"bazelbuild/bazel","slug":"unsupported-junit-runner-api-version-junit-api-v","errorCode":null,"errorMessage":"Unsupported JUnit Runner API version ${JUNIT_API_VERSION_PROPERTY}=${junitApiVersion} (must be \\\"1\\\")","messagePattern":"Unsupported JUnit Runner API version (.+?)=(.+?) \\(must be \\\\\"1\\\\\"\\)","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java_tools/junitrunner/java/com/google/testing/junit/runner/junit4/JUnit4Config.java","lineNumber":110,"sourceCode":"  }\n\n  /**\n   * Gets the version of the JUnit Runner that the test is expecting.\n   * Some features may be enabled or disabled based on this value.\n   *\n   * @return api version\n   * @throws IllegalStateException if the API version is unsupported.\n   */\n  public int getJUnitRunnerApiVersion() {\n    int apiVersion = 0;\n    try {\n      apiVersion = Integer.parseInt(junitApiVersion);\n    } catch (NumberFormatException e) {\n      // ignore; handled below\n    }\n\n    if (apiVersion != 1) {\n      throw new IllegalStateException(\n          \"Unsupported JUnit Runner API version \" + JUNIT_API_VERSION_PROPERTY + \"=\"\n          + junitApiVersion + \" (must be \\\\\\\"1\\\\\\\")\");\n    }\n    return apiVersion;\n  }\n\n  /**\n   * Returns the value of the {@code test_runner_fail_fast} option, or <code>false<code/> if\n   * it was not specified.\n   */\n  boolean getTestRunnerFailFast() {\n    return testRunnerFailFast;\n  }\n\n  /**\n   * Returns a regular expression representing an inclusive filter.\n   * Only test descriptions that match this regular expression should be run.\n   */","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/bazelbuild/bazel/blob/e6e199d0601a244511b4cf18c8b2828aa73db1fd/src/java_tools/junitrunner/java/com/google/testing/junit/runner/junit4/JUnit4Config.java#L92-L128","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\njava -Dcom.google.testing.junit.runner.apiVersion=2 com.google.testing.junit.runner.junit4.JUnit4Runner ...\n# after\njava -Dcom.google.testing.junit.runner.apiVersion=1 com.google.testing.junit.runner.junit4.JUnit4Runner ...","handlingStrategy":"validation","validationCode":"// before launching the runner\nString v = System.getProperty(\"com.google.testing.junit.runner.apiVersion\", \"1\").trim();\nif (!\"1\".equals(v)) {\n  throw new IllegalArgumentException(\n      \"Refusing to run with apiVersion=\" + v + \"; only 1 is supported\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  runner.run();\n} catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"JUnit Runner API version\")) {\n    // report config problem distinctly from test failures\n  } else { throw e; }\n}","preventionTips":["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."],"tags":["junit","bazel","system-property","version-mismatch"],"backgroundTag":null,"analyzedSha":"e6e199d0601a244511b4cf18c8b2828aa73db1fd","analyzedAt":"2026-08-14T10:24:27.848Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}