BoundaryML/baml · error

unknown run-verb flag

Error message

unknown run-verb flag `--{stripped}` in script body. Only `--function <name>` is recognized before `--`; put target arguments after `--`.

What it means

Parse guard for script bodies in baml.toml [scripts]: a token starting with `--` (other than `--function`) appeared before the `--` separator. V1 deliberately recognizes only `--function <name>` pre-separator; run-verb flags like `--json-args` are rejected at load time rather than silently dropped, because the toml loader is the last chance to surface the typo before the script runs.

Solutions

1. Move target arguments after the `--` separator
2. Remove the unknown flag if it is not meant for the target
3. Use `--function <name>` if the intent was to select a BAML function

Example fix

// before
["--verbose", "input.txt"]
// after
["--function", "MyFunc", "--", "--verbose", "input.txt"]

function splitScriptBody(tokens) {
  const sep = tokens.indexOf('--');
  const head = sep === -1 ? tokens : tokens.slice(0, sep);
  const bad = head.filter((t, i) => t.startsWith('--') && t !== '--function' && !(t === '--function' && i + 1 < head.length));
  if (bad.length) throw new Error('move these flags after -- : ' + bad.join(' '));
}

try { await baml.run(tokens); } catch (e) { if (String(e).includes('unknown run-verb flag')) { console.error('Only --function is allowed before --; move target args after --'); } else throw e; }

When it happens

Trigger: `parse_script_body` encounters a token starting with `--` that is not `--function` and not the `--` separator itself, e.g. a script body of `["--verbose", "--", "arg"]`.

Common situations: Putting flags meant for the target function/script (like `--param` or `--file`) before `--`; copying flags from other CLI verbs into the script body.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• are mutually exclusive dispatch modes — pick one.
• script body has `--function` without a value
• unexpected token ` ` in script body. Script bodies have the…
• {bail_context}
• Cannot generate HIR/bytecode due to validation errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/30170d56ccd1d16e. Report an issue: GitHub.

Appendix: source

Thrown at baml_language/crates/baml_cli/src/run_command.rs:116

        // Pre-separator: only `--function <value>` is recognized as a
        // run-verb flag inside a script body in v1. Other run-verb flags
        // (`--json-args`, `--include-generated`, etc.) are deliberately rejected
        // here rather than silently dropped — the toml loader is the
        // last chance to surface a typo before the script runs.
        if token == "--function" {
            i += 1;
            if i < tokens.len() {
                function = Some(tokens[i].clone());
                i += 1;
            } else {
                anyhow::bail!("script body has `--function` without a value");
            }
            continue;
        }

        if let Some(stripped) = token.strip_prefix("--") {
            anyhow::bail!(
                "unknown run-verb flag `--{stripped}` in script body. \
                 Only `--function <name>` is recognized before `--`; \
                 put target arguments after `--`."
            );
        }

        anyhow::bail!(
            "unexpected token `{token}` in script body. \
             Script bodies have the shape `[--function <name>] [-- <target-args>...]`."
        );
    }

    Ok(ScriptExpansion {
        function,
        extra_args,
    })
}

View on GitHub (pinned to bd85ce9dee)