block/buzz · error · io::Error (AlreadyExists)

PI_ACP_PI_COMMAND is managed by Buzz; unset it before starti

Error message

PI_ACP_PI_COMMAND is managed by Buzz; unset it before starting a managed Pi agent

What it means

Raised in PiLaunchOverride::prepare when inherited_pi_command_is_set is true, i.e. the environment variable PI_ACP_PI_COMMAND is present while Buzz is launching a managed Pi agent. That variable is reserved for Buzz's own management of the Pi subprocess; a user- or parent-supplied value would conflict with the launcher override Buzz generates, so prepare refuses with this InvalidData io::Error. Generic validation guard; the input at fault is the inherited PI_ACP_PI_COMMAND environment variable.

Source

Thrown at crates/buzz-acp/src/pi_launcher.rs:47

impl PiLaunchOverride {
    /// Prepare a Pi launcher when the configured ACP adapter is `pi-acp`.
    ///
    /// Returns the prompt that still needs ordinary ACP delivery. For Pi, the
    /// base prompt moves into Pi's native system role and is therefore removed
    /// from first-turn user framing. Other adapters receive it unchanged.
    pub(crate) fn prepare(
        agent_command: &str,
        base_prompt: Option<String>,
        managed_skills_dir: &Path,
        inherited_pi_command_is_set: bool,
    ) -> io::Result<(Option<Self>, Option<String>)> {
        if crate::config::normalize_agent_command_identity(agent_command) != "pi-acp" {
            return Ok((None, base_prompt));
        }

        if inherited_pi_command_is_set {
            return Err(io::Error::new(
                io::ErrorKind::AlreadyExists,
                "PI_ACP_PI_COMMAND is managed by Buzz; unset it before starting a managed Pi agent",
            ));
        }

        // Buzz owns PI_ACP_PI_COMMAND and always uses it to point pi-acp at
        // this generated launcher. The launcher resolves the ordinary `pi`
        // command from Buzz's effective PATH.
        let prepared = Self::create("pi", base_prompt.as_deref(), managed_skills_dir)?;
        Ok((Some(prepared), None))
    }

    pub(crate) fn launcher_path(&self) -> &Path {
        &self.launcher
    }

    fn create(
        pi_command: &str,

View on GitHub (pinned to dad5a33865)

Solutions

1. Unset PI_ACP_PI_COMMAND in the environment before starting the managed Pi agent
2. Remove any shell profile, wrapper script, or harness export that sets PI_ACP_PI_COMMAND for agent subprocesses
3. If a custom Pi command is genuinely needed, use Buzz's supported configuration option for the agent command instead of the managed env var

When it happens

Trigger: Thrown at crates/buzz-acp/src/pi_launcher.rs:47 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of block/buzz@dad5a33865 (2026-09-05). Data as JSON: /api/errors/f6e37f87d6e074b3. Report an issue: GitHub.