bazelbuild/bazel · error · IOException

unknown flag: %s

Error message

unknown flag: %s

What it means

The Starlark interpreter CLI supports a fixed flag set: -c <cmd>, -cpuprofile <file>, and '--'. Any other token starting with '-' during the flag-parsing prefix is rejected with this IOException ('unknown flag: X') before the script runs.

Source

Thrown at src/main/java/net/starlark/java/cmd/Main.java:197

      if (!args[i].startsWith("-")) {
        break;
      }
      if (args[i].equals("--")) {
        i++;
        break;
      }
      if (args[i].equals("-c")) {
        if (i + 1 == args.length) {
          throw new IOException("-c <cmd> flag needs an argument");
        }
        cmd = args[++i];
      } else if (args[i].equals("-cpuprofile")) {
        if (i + 1 == args.length) {
          throw new IOException("-cpuprofile <file> flag needs an argument");
        }
        cpuprofile = args[++i];
      } else {
        throw new IOException("unknown flag: " + args[i]);
      }
    }
    // positional arguments
    if (i < args.length) {
      if (i + 1 < args.length) {
        throw new IOException("too many positional arguments");
      }
      file = args[i];
    }

    if (cpuprofile != null) {
      FileOutputStream out = new FileOutputStream(cpuprofile);
      Starlark.startCpuProfile(out, Duration.ofMillis(10));
    }

    int exit;
    if (file == null) {
      if (cmd != null) {

View on GitHub (pinned to e6e199d060)

Solutions

1. Remove the unsupported flag; only -c, -cpuprofile and -- are accepted.
2. Use '--' to end flag parsing when a positional argument starts with '-': `starlark -- -weird.star`.
3. Pass JVM options to the java launcher (before the class/jar), not to this CLI.

Example fix

# before
starlark -Dfoo=bar script.star

# after
java -Dfoo=bar -cp starlark.jar net.starlark.java.cmd.Main script.star

# Whitelist flags before forwarding
for a in "$@"; do
  case "$a" in
    -c|-cpuprofile|--|*.star) ;;
    -*) echo "unsupported flag: $a" >&2; exit 2 ;;
  esac
done
exec starlark "$@"

When it happens

Trigger: Passing unsupported flags like `starlark -v script.star`, `--verbose`, `-Dkey=val`, or a script path that begins with '-'; forgetting '--' before a filename that starts with '-'.

Common situations: Users assuming this CLI shares flags with the Bazel client or the go starlark binary; passing JVM system properties to the wrong side of '--'; renamed flags after switching interpreter distributions.

Related errors

• -c <cmd> flag needs an argument
• -cpuprofile <file> flag needs an argument
• too many positional arguments
• Usage: %s -- command arg1 @args
• \nUsage: %s -- command arg1 @args\n

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