Fleet session capture id is already in use or unavailable

Error message

Fleet session capture id is already in use or unavailable

What it means

When a Fleet capture destination is configured (both CODEWHALE_FLEET_CAPTURE_ID and CODEWHALE_FLEET_CAPTURE_DIR are set), run_exec_agent requires the capture session id to be free: it loads the session from the SessionManager and only tolerates a NotFound error. Any other load result — the session already exists, or loading failed with a non-NotFound I/O error — throws this error to prevent overwriting or appending to an existing capture.

Solutions

Generate a fresh CODEWHALE_FLEET_CAPTURE_ID (new UUID) for this run instead of reusing the old one.
Inspect CODEWHALE_FLEET_CAPTURE_DIR and remove or archive the existing session file for that id if it is no longer needed.
Check permissions on the capture directory; a non-NotFound load error (e.g. EACCES) is reported under the same message — fix the permission problem.
If the intent was to continue an existing session, that is unsupported for Fleet capture (`Fleet capture cannot resume a session`); drop the resume flag and use a new id.

Example fix

// before
CODEWHALE_FLEET_CAPTURE_ID=3f9c... (already captured)
// after
CODEWHALE_FLEET_CAPTURE_ID=$(uuidgen) CODEWHALE_FLEET_CAPTURE_DIR=/tmp/fleet-captures codewhale exec ...

Defensive patterns

Strategy: validation

Validate before calling

# Shell pre-check before launching exec with capture
id="$CODEWHALE_FLEET_CAPTURE_ID"; dir="$CODEWHALE_FLEET_CAPTURE_DIR"
[ -n "$id" ] && [ -n "$dir" ] || { echo "capture pair incomplete"; exit 2; }
[ -f "$dir/$id.session" ] && { echo "capture id already in use"; exit 3; }

Try / catch

match run_exec_agent(...).await {
    Err(e) if e.to_string().contains("already in use") => {
        eprintln!("rotate CODEWHALE_FLEET_CAPTURE_ID and retry");
    }
    other => other,
}

Prevention

Always generate a fresh UUID per capture run; never replay a used capture id.
Archive or delete finished capture sessions before reuse of a directory.
Ensure the capture directory is writable by the exec process to avoid non-NotFound load errors.

When it happens

Trigger: Starting `codewhale exec` with CODEWHALE_FLEET_CAPTURE_ID set to a UUID that already has a stored session file in CODEWHALE_FLEET_CAPTURE_DIR, or where `SessionManager::load_session` fails with an error other than NotFound (e.g. permission or corruption).

Common situations: Re-running the same fleet worker dispatch without rotating the capture id; a stale capture directory left over from a previous run; the capture directory contains a session file written by an older Codewhale version that now fails to deserialize.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/acea560dfd5ef58d. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/exec_agent.rs:354

        .unwrap_or_default();
    if let Some(envelope) = fleet_authority {
        crate::tools::spec::install_process_tool_authority(envelope).map_err(anyhow::Error::msg)?;
    }

    let fleet_capture = match (
        std::env::var("CODEWHALE_FLEET_CAPTURE_ID").ok(),
        std::env::var_os("CODEWHALE_FLEET_CAPTURE_DIR"),
    ) {
        (Some(id), Some(dir)) => {
            uuid::Uuid::parse_str(&id).context("invalid Fleet session capture id")?;
            anyhow::ensure!(
                resume_session.is_none(),
                "Fleet capture cannot resume a session"
            );
            let manager = SessionManager::new(PathBuf::from(dir))?;
            match manager.load_session(&id) {
                Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
                _ => anyhow::bail!("Fleet session capture id is already in use or unavailable"),
            }
            Some((id, manager))
        }
        (None, None) => None,
        _ => anyhow::bail!("incomplete Fleet session capture destination"),
    };

    let route = resolve_cli_exec_route(config, model, prompt, force_configured_route).await?;
    let execution_config = config_for_cli_route(config, &route);
    let auto_model = route.auto_model;
    let effective_provider = route.provider;
    let effective_model = route.model;
    let validated_route = crate::route_runtime::resolve_runtime_route(
        &execution_config,
        effective_provider,
        Some(&effective_model),
    )
    .map_err(anyhow::Error::msg)?

View on GitHub (pinned to 73e0f67d83)