BoundaryML/baml · error

Target ` ` declares a parameter named `help`, which…

Error message

Target `{function_name}` declares a parameter named `help`, which collides with the auto-derived `--help` flag. Rename this parameter to be used as an entry point.

What it means

`--help` is auto-derived by the BAML CLI, so an entry-point function may not declare a parameter literally named `help`. `validate_help_param` scans the target's resolved parameters and bails if any collides, reserving the flag for usage output.

Solutions

1. Rename the `help` parameter in the function signature (e.g. `show_help`, `help_text`).
2. Update all call sites, test invocations, and any `--json-args` payloads referencing the old name.
3. Re-run `baml run <target> --help` to confirm the derived flag works.

Example fix

// before
function myFunc(help: bool) { ... }

// after
function myFunc(show_help: bool) { ... }

fn uses_reserved_param(params: &[&str]) -> bool {
    params.iter().any(|p| *p == "help")
}

match result {
    Err(e) if e.to_string().contains("collides with the auto-derived `--help` flag") => {
        eprintln!("rename the `help` parameter in the target signature");
    }
    other => other,
}

When it happens

Trigger: Running or packing a target function whose signature contains a parameter named `help`; the check runs in `run_with_reporter` and again inside `dispatch_target_with_context` under BEP-027 conventions.

Common situations: Writing a function that mirrors a CLI-style API with a `help` option, or migrating an existing function whose parameter name happens to be `help`.

Related errors

• are mutually exclusive dispatch modes — pick one.
• {bail_context}
• Cannot generate HIR/bytecode due to validation errors
• compilation failed
• compilation failed

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

Appendix: source

Thrown at baml_language/crates/baml_exec/src/dispatch.rs:37

/// Result of dispatching a target.
pub enum DispatchResult {
    /// Target completed successfully.
    Ok,
    /// Target raised an error (already printed to stderr).
    TargetError,
    /// Target called `baml.sys.exit(code)`. The caller is responsible for
    /// terminating the process with this code (clamped to the shell's
    /// range as appropriate — typically 0..=255 on Unix).
    Exit(i64),
}

/// Reject targets whose signature declares a parameter named `help`.
pub fn validate_help_param(engine: &BexEngine, function_name: &str) -> Result<()> {
    let params = engine
        .function_params(function_name)
        .with_context(|| format!("failed to resolve target `{function_name}`"))?;
    if params.iter().any(|(name, _, _)| *name == "help") {
        anyhow::bail!(
            "Target `{function_name}` declares a parameter named `help`, \
             which collides with the auto-derived `--help` flag. \
             Rename this parameter to be used as an entry point."
        );
    }
    Ok(())
}

/// Narrow a `baml.sys.exit(code)` value (BAML `int` = `i64`) to the `i32`
/// that `std::process::exit` and C's `exit(int)` take.
pub fn clamp_exit_code(code: i64) -> i32 {
    i32::try_from(code).unwrap_or(if code < 0 { i32::MIN } else { i32::MAX })
}

/// Invoke `target_name` with parameters drawn from `cli_values` (and
/// optionally `json_args`), then write the return value to stdout.
///
/// `cli_values` is the already-typed map produced by

View on GitHub (pinned to bd85ce9dee)