astrid-runtime/astrid · error

unsupported MCP readiness format

Error message

unsupported MCP readiness format '{other}'; use hook, pretty, or json

What it means

ReadyFormat::parse converts the --format flag of `astrid mcp ready` into the ReadyFormat enum. It only accepts the literal strings hook, pretty, or json; any other value is rejected with this error listing the valid choices.

Solutions

1. Use one of the exact lowercase values: hook, pretty, or json.
2. Run `astrid mcp ready --help` to confirm the accepted formats for your installed version.
3. If a wrapper script supplies the format, whitelist it to {hook,pretty,json} before invoking the CLI.
4. Upgrade/downgrade the CLI if you need a format introduced in a different version.

Example fix

// before
astrid mcp ready --format JSON
// after
astrid mcp ready --format json

const READY_FORMATS: [&str; 3] = ["hook", "pretty", "json"];
fn valid_format(f: &str) -> Result<(), String> {
    if READY_FORMATS.contains(&f) { Ok(()) } else { Err(format!("format '{f}' not in {{hook, pretty, json}}")) }
}

fn is_ready_format(v: &str) -> bool { matches!(v, "hook" | "pretty" | "json") }

match ready_format.parse() {
    Ok(fmt) => run_ready(fmt),
    Err(e) if e.to_string().contains("unsupported MCP readiness format") =>
        eprintln!("{e}; pass --format hook|pretty|json"),
    Err(e) => eprintln!("{e:#}"),
}

When it happens

Trigger: Calling `astrid mcp ready --format <value>` (or the parse API) with any string other than exactly "hook", "pretty", or "json", including typos like "JSON", "hooks", or "text".

Common situations: Case-sensitive typo (JSON instead of json); assuming an undocumented format exists; scripting that interpolates a config value not in the allowed set; older/newer CLI versions with a different format vocabulary.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• requires NAME=PATH
• requires non-empty NAME=PATH
• --git-history requires NAME=REPO::RELATIVE_PATH
• invalid value for . : expected one of , got
• --output requires a path

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/f10e8dc2fcb00092. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-cli/src/commands/mcp/lifecycle.rs:756

    remove_gateway_startup_lease(None).context("shutdown stage gateway.startup_cleanup")?;
    drop(lifecycle);
    Ok(())
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ReadyFormat {
    Hook,
    Pretty,
    Json,
}

impl ReadyFormat {
    fn parse(value: &str) -> Result<Self> {
        match value {
            "hook" => Ok(Self::Hook),
            "pretty" => Ok(Self::Pretty),
            "json" => Ok(Self::Json),
            other => anyhow::bail!(
                "unsupported MCP readiness format '{other}'; use hook, pretty, or json"
            ),
        }
    }
}

fn emit_ready(format: ReadyFormat, record: &GatewayReady) -> Result<()> {
    match format {
        ReadyFormat::Hook => println!("ready"),
        ReadyFormat::Pretty => println!("MCP gateway ready (principal {})", record.principal),
        ReadyFormat::Json => println!("{}", serde_json::to_string(record)?),
    }
    Ok(())
}

fn spawn_gateway(principal: &PrincipalId) -> Result<()> {
    let executable =
        std::env::current_exe().context("failed to resolve the Astrid CLI executable")?;

View on GitHub (pinned to affd8760f4)