bazelbuild/bazel · error · OptionsParsingException

Error reading params file: %s %s

Error message

Error reading params file: %s %s

What it means

ParamsFilePreProcessor.preProcess catches any RuntimeException or IOException raised while resolving or parsing the '@' params file path, and rethrows as this error with the path and underlying reason. Common underlying causes: the file does not exist, is unreadable, or the params-file parser rejected its contents.

Source

Thrown at src/main/java/com/google/devtools/common/options/ParamsFilePreProcessor.java:68

   * @return A list of arguments suitable for parsing.
   * @throws OptionsParsingException if the path does not exist.
   */
  @Override
  public List<ArgAndFallbackData> preProcess(List<ArgAndFallbackData> args)
      throws OptionsParsingException {
    if (!args.isEmpty() && args.get(0).arg.startsWith("@")) {
      if (args.size() > 1) {
        throw new OptionsParsingException(
            String.format(
                TOO_MANY_ARGS_ERROR_MESSAGE_FORMAT,
                Lists.transform(args, argAndFallbackData -> argAndFallbackData.arg)),
            args.get(0).arg);
      }
      Path path = fs.getPath(args.get(0).arg.substring(1));
      try {
        return ArgAndFallbackData.wrapWithFallbackData(parse(path), args.get(0).fallbackData);
      } catch (RuntimeException | IOException e) {
        throw new OptionsParsingException(
            String.format(ERROR_MESSAGE_FORMAT, path, e.getMessage()), args.get(0).arg, e);
      }
    }
    return args;
  }

  /**
   * Parses the paramsFile and returns a list of argument tokens to be further processed by the
   * {@link OptionsParser}.
   *
   * @param paramsFile The path of the params file to parse.
   * @return a list of argument tokens.
   * @throws IOException if there is an error reading paramsFile.
   * @throws OptionsParsingException if there is an error reading paramsFile.
   */
  protected abstract List<String> parse(Path paramsFile)
      throws IOException, OptionsParsingException;
}

View on GitHub (pinned to e6e199d060)

Solutions

1. Verify the path exists and is readable at the exact location Bazel resolves it (relative to the workspace/invocation cwd)
2. Ensure the file is generated before the Bazel invocation in the build pipeline
3. Check the underlying message after the path — for parse issues, fix the params file format (--param_file=file_format=shell|simple|multiline) or quoting
4. Use an absolute or workspace-relative path that survives CI directory changes

Example fix

# before
bazel build @/stale/path/args.txt
# after
gen //tools:args && bazel build @bazel-out/k8-fastbuild/bin/tools/args.txt

# Verify the params file resolves before invoking
p="${1#@}"
[ -f "$p" ] || { echo "params file not found: $p" >&2; exit 2; }
[ -r "$p" ] || { echo "params file unreadable: $p" >&2; exit 2; }

Catch OptionsParsingException from preProcess/parse; when the message starts with 'Error reading params file:', surface the underlying IOException reason (missing file, permission) rather than retrying.

When it happens

Trigger: Passing '@nonexistent.txt' as the only argument; a params file with a bad --param_file=file_format value; permission errors or a directory path instead of a file; relative path resolved against the wrong filesystem root.

Common situations: CI checkout missing a generated args file; stale absolute path from another machine; params file with Windows line endings or wrong file_format flag; tool generating the file after Bazel starts.

Related errors

• Expected value after %s
• A params file must be the only argument: %s
• Malformed value of --invocation_policy:
• Tried to expand option too many times
• Unrecognized arguments:

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