astrid-runtime/astrid · error

grant preflight returned an unexpected response

Error message

grant preflight returned an unexpected response: {other:?}

What it means

preflight_grants sends a grant preflight request to the admin API and expects an AdminResponseBody::Success. Any other response variant triggers this bail, meaning the server replied with something the preflight path does not understand.

Solutions

1. Check server and CLI versions; align the admin API version so preflight returns Success.
2. Inspect the `other:?` debug output in the message to see which variant came back and why.
3. Verify the endpoint URL/protocol (HTTP vs socket, admin route) used for preflight.
4. Capture the response and report/fix the deserialization mapping for the new variant.

// pre-check admin endpoint reachability and version
let ok = admin_ping().is_ok();
if !ok { eprintln!("admin API unavailable; preflight will fail"); }

match preflight_grants().await {
    Err(e) if e.to_string().contains("unexpected response") => {
        eprintln!("admin API version mismatch: {e}");
        // inspect variant, upgrade CLI/server
    }
    Err(e) => return Err(e),
    Ok(()) => Ok(()),
}

When it happens

Trigger: The grant preflight HTTP request succeeded (context wraps transport failures separately) but into_result returned a body that is neither Success nor a handled error — an unexpected AdminResponseBody variant.

Common situations: Server running a newer/older API version returning a new response variant; a proxy returning an HTML/error page parsed into an unexpected body; misrouted endpoint returning a different admin response type.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• GitHub release has missing or empty tag_name
• daemon did not return capsule metadata for WIT GC
• FUSE service returned an incompatible unmount response
• GitHub API error querying release tag
• GitHub API returned fetching release of /

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

Appendix: source

Thrown at crates/astrid-cli/src/commands/init_grant.rs:156

    preflight_sequence(
        crate::commands::daemon::ensure_daemon("init grant preflight"),
        || async move {
            let mut client = crate::admin_client::connect_for_workspace_as(operator.clone())
                .await
                .context("grant preflight could not connect to the selected workspace daemon")?;
            let body = client
                .request(AdminRequestKind::AgentModify {
                    principal: target.clone(),
                    add_groups: Vec::new(),
                    remove_groups: Vec::new(),
                    add_capsules: Vec::new(),
                    remove_capsules: Vec::new(),
                })
                .await
                .context("grant preflight request failed")?;
            match crate::admin_client::into_result(body)? {
                AdminResponseBody::Success(_) => Ok(()),
                other => bail!("grant preflight returned an unexpected response: {other:?}"),
            }
        },
    )
    .await
}

async fn preflight_sequence<E, C, F>(ensure_daemon: E, check: C) -> anyhow::Result<()>
where
    E: Future<Output = anyhow::Result<()>>,
    C: FnOnce() -> F,
    F: Future<Output = anyhow::Result<()>>,
{
    ensure_daemon
        .await
        .context("grant preflight could not ensure the runtime daemon")?;
    check().await
}

View on GitHub (pinned to affd8760f4)