bazelbuild/bazel · error · OptionsParsingException

A params file must be the only argument: %s

Error message

A params file must be the only argument: %s

What it means

ParamsFilePreProcessor.preProcess only supports a params file when it is the sole argument: if args[0] starts with '@' and there are additional args, it refuses with this error listing the full argument list. This mirrors Bazel's rule that a params file must stand alone as the entire argument vector.

Source

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

  private final FileSystem fs;

  ParamsFilePreProcessor(FileSystem fs) {
    this.fs = fs;
  }

  /**
   * Parses the param file path and replaces the arguments list with the contents if one exists.
   *
   * @param args A list of arguments that may contain @<path> to a params file.
   * @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

View on GitHub (pinned to e6e199d060)

Solutions

1. Move every argument into the params file so '@file' is the only argument
2. Or drop the '@' indirection and pass the arguments directly
3. Fix generators to write new args into the file instead of appending them after '@file' on the command line

Example fix

# before
bazel build @args.txt --verbose_failures
# after (add --verbose_failures into args.txt)
bazel build @args.txt

# Ensure '@file' is the sole argument when present
case " $* " in
  *\ @*) if [ "$#" -ne 1 ]; then echo "A params file must be the only argument" >&2; exit 2; fi;;
esac

When it happens

Trigger: Invoking with `@params.txt extra_flag` or `@params.txt //target` — the '@file' token plus anything else. Also programmatic calls that prepend/append flags around a params file argument.

Common situations: Wrappers that add a tag like --config=ci after a params file; incremental scripts appending targets after '@file'; converting a long argv to a params file but leaving one flag outside.

Related errors

• Expected value after %s
• Error reading params file: %s %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/bc54b0b5ecf09d92. Report an issue: GitHub.