{"record":{"id":"bc54b0b5ecf09d92","repo":"bazelbuild/bazel","slug":"a-params-file-must-be-the-only-argument-s","errorCode":null,"errorMessage":"A params file must be the only argument: %s","messagePattern":"A params file must be the only argument: (.+?)","errorType":"exception","errorClass":"OptionsParsingException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/google/devtools/common/options/ParamsFilePreProcessor.java","lineNumber":58,"sourceCode":"  private final FileSystem fs;\n\n  ParamsFilePreProcessor(FileSystem fs) {\n    this.fs = fs;\n  }\n\n  /**\n   * Parses the param file path and replaces the arguments list with the contents if one exists.\n   *\n   * @param args A list of arguments that may contain @&lt;path&gt; to a params file.\n   * @return A list of arguments suitable for parsing.\n   * @throws OptionsParsingException if the path does not exist.\n   */\n  @Override\n  public List<ArgAndFallbackData> preProcess(List<ArgAndFallbackData> args)\n      throws OptionsParsingException {\n    if (!args.isEmpty() && args.get(0).arg.startsWith(\"@\")) {\n      if (args.size() > 1) {\n        throw new OptionsParsingException(\n            String.format(\n                TOO_MANY_ARGS_ERROR_MESSAGE_FORMAT,\n                Lists.transform(args, argAndFallbackData -> argAndFallbackData.arg)),\n            args.get(0).arg);\n      }\n      Path path = fs.getPath(args.get(0).arg.substring(1));\n      try {\n        return ArgAndFallbackData.wrapWithFallbackData(parse(path), args.get(0).fallbackData);\n      } catch (RuntimeException | IOException e) {\n        throw new OptionsParsingException(\n            String.format(ERROR_MESSAGE_FORMAT, path, e.getMessage()), args.get(0).arg, e);\n      }\n    }\n    return args;\n  }\n\n  /**\n   * Parses the paramsFile and returns a list of argument tokens to be further processed by the","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/bazelbuild/bazel/blob/e6e199d0601a244511b4cf18c8b2828aa73db1fd/src/main/java/com/google/devtools/common/options/ParamsFilePreProcessor.java#L40-L76","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Move every argument into the params file so '@file' is the only argument","Or drop the '@' indirection and pass the arguments directly","Fix generators to write new args into the file instead of appending them after '@file' on the command line"],"exampleFix":"# before\nbazel build @args.txt --verbose_failures\n# after (add --verbose_failures into args.txt)\nbazel build @args.txt","handlingStrategy":"validation","validationCode":"# Ensure '@file' is the sole argument when present\ncase \" $* \" in\n  *\\ @*) if [ \"$#\" -ne 1 ]; then echo \"A params file must be the only argument\" >&2; exit 2; fi;;\nesac","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat '@file' as the complete argv, not an include directive","Write additional flags into the params file rather than appending them on the CLI","Generate the params file last, after all flags are known"],"tags":["bazel","options","params-file","flag-parsing"],"backgroundTag":null,"analyzedSha":"e6e199d0601a244511b4cf18c8b2828aa73db1fd","analyzedAt":"2026-08-14T10:24:27.848Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}