affaan-m/ECC · error · anyhow::Error

template {template_name} requires {} session slots but only

Error message

template {template_name} requires {} session slots but only {available_slots} available

What it means

When launching sessions from a template, the system counts live sessions (Pending, Running, Idle, Stale) and subtracts from max_parallel_sessions to compute available slots. If the template's step count exceeds the remaining slots, the operation bails. This prevents overcommitting parallel session capacity.

Source

Thrown at ecc2/src/session/manager.rs:637

        .transpose()?;
    let vars = build_template_variables(&repo_root, source_session.as_ref(), task, variables);
    let template = cfg.resolve_orchestration_template(template_name, &vars)?;
    let live_sessions = db
        .list_sessions()?
        .into_iter()
        .filter(|session| {
            matches!(
                session.state,
                SessionState::Pending
                    | SessionState::Running
                    | SessionState::Idle
                    | SessionState::Stale
            )
        })
        .count();
    let available_slots = cfg.max_parallel_sessions.saturating_sub(live_sessions);
    if template.steps.len() > available_slots {
        anyhow::bail!(
            "template {template_name} requires {} session slots but only {available_slots} available",
            template.steps.len()
        );
    }

    let default_profile = cfg
        .default_agent_profile
        .as_deref()
        .map(|name| cfg.resolve_agent_profile(name))
        .transpose()?;
    let base_grouping = SessionGrouping {
        project: Some(
            source_session
                .as_ref()
                .map(|session| session.project.clone())
                .unwrap_or_else(|| default_project_label(&repo_root)),
        ),
        task_group: Some(

View on GitHub (pinned to 01e15490f0)

Solutions

Increase max_parallel_sessions in config to accommodate template step count plus any in-flight sessions
Stop or complete idle/stale sessions to free slots before launching the template
Reduce the number of steps in the template
Query the live session count before launching and compare against configured capacity

Example fix

// before
launch_template(template, cfg).await?;

// after
let live = sessions.iter()
    .filter(|s| matches!(s.state, SessionState::Pending | SessionState::Running | SessionState::Idle | SessionState::Stale))
    .count();
let available = cfg.max_parallel_sessions.saturating_sub(live);
if template.steps.len() > available {
    return Err(anyhow!("Not enough slots: need {}, have {}", template.steps.len(), available));
}
launch_template(template, cfg).await?;

Defensive patterns

Strategy: validation

Validate before calling

fn available_session_slots(db: &StateStore, cfg: &Config) -> Result<usize> {
    let sessions = db.list_sessions()?;
    let live = sessions.iter()
        .filter(|s| matches!(s.state, SessionState::Pending | SessionState::Running | SessionState::Idle | SessionState::Stale))
        .count();
    Ok(cfg.max_parallel_sessions.saturating_sub(live))
}

// Before launching:
let available = available_session_slots(db, cfg)?;
if template.steps.len() > available {
    return Err(anyhow!("need {} slots, only {} available", template.steps.len(), available));
}

Prevention

Track live session count in the caller and block template launches when capacity is insufficient
Set max_parallel_sessions generously enough to handle your largest template
Implement a queue that waits for slots to free up instead of failing immediately

When it happens

Trigger: Calling the template-launch path when template.steps.len() exceeds (cfg.max_parallel_sessions minus the count of sessions currently in Pending, Running, Idle, or Stale states).

Common situations: Running several concurrent agent sessions that fill capacity, then launching a multi-step template. Or setting max_parallel_sessions too low for the template size in config.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/72daf543f3a87dfa. Report an issue: GitHub.