bazelbuild/bazel · error · RuntimeException

Error writing shard file ${shardFile}

Error message

Error writing shard file ${shardFile}

What it means

Thrown by ShardingEnvironment.touchShardFile while creating or timestamping the file named by TEST_SHARD_STATUS_FILE. Under sharded bazel test execution each shard must touch this file so Bazel knows the shard started; failure to create the file or update its mtime raises an IOException that is wrapped in a RuntimeException.

Source

Thrown at src/java_tools/junitrunner/java/com/google/testing/junit/runner/sharding/ShardingEnvironment.java:81

  /**
   * Creates the shard file that is used to indicate that tests are
   * being sharded.
   */
  public void touchShardFile() {
    String shardStatusPath = System.getenv("TEST_SHARD_STATUS_FILE");
    File shardFile = (shardStatusPath == null ? null : new File(shardStatusPath));
    touchShardFile(shardFile);
  }

  // VisibleForTesting
  static void touchShardFile(File shardFile) {
    if (shardFile != null) {
      try {
        if (!shardFile.createNewFile() && !shardFile.setLastModified(System.currentTimeMillis())) {
          throw new IOException("Unable to update modification time of " + shardFile);
        }
      } catch (IOException e) {
        throw new RuntimeException("Error writing shard file " + shardFile, e);
      }
    }
  }

  /**
   * Returns the test sharding strategy optionally specified by the JVM flag
   * {@link #TEST_SHARDING_STRATEGY}, which maps to the enums in
   * {@link com.google.testing.junit.runner.sharding.ShardingFilters.ShardingStrategy}.
   */
  public String getTestShardingStrategy() {
    return System.getProperty(TEST_SHARDING_STRATEGY);
  }
}

View on GitHub (pinned to e6e199d060)

Solutions

1. Run the test through bazel test so the harness provides a writable TEST_SHARD_STATUS_FILE path.
2. If wrapping the runner, point TEST_SHARD_STATUS_FILE at a writable directory (the runner only needs create/touch permission).
3. For sandboxing issues, add the status-file directory to the sandbox's writable inputs (e.g. --sandbox_writable_path) or disable sandboxing for that test.
4. Check disk space and filesystem mtime support on the host mounting the output tree.

Example fix

# before
bazel test --test_sharding_strategy=... //foo  # TEST_SHARD_STATUS_FILE dir not writable
# after
bazel test --sandbox_writable_path=/output-baseline/execroot/... //foo

// before running sharded tests
String shardStatus = System.getenv("TEST_SHARD_STATUS_FILE");
if (shardStatus != null) {
  File dir = new File(shardStatus).getAbsoluteFile().getParentFile();
  if (dir == null || !dir.canWrite()) {
    throw new IllegalStateException("Shard status dir not writable: " + dir);
  }
}

When it happens

Trigger: closeShardFile() runs after the test with TEST_SHARD_STATUS_FILE set and either createNewFile() fails (unwritable directory, read-only filesystem, disk full) or the file exists but setLastModified() returns false (filesystem refusing mtime updates, e.g. some network/overlay filesystems).

Common situations: Sandboxed executions where the shard-status directory is not included in the sandbox writable list; overlayfs/NFS mounts that do not honor utime; running sharded tests under a manually minimal container lacking write access to the runfiles tree.

Related errors

• Could not write exit file at ${file}
• Could not create custom sharding strategy class ${strategy}
• Unsupported JUnit Runner API version ${JUNIT_API_VERSION_PRO
• No filter expression specified after ${arg}
• This converter doesn't support Starlark reversal.

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