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

template requires session slots but only available

Error message

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

What it means

This error is thrown by launch_orchestration_template when a user tries to launch an orchestration template whose number of steps exceeds the configured maximum parallel sessions minus the currently live (non-stale) sessions. The library refuses to launch because it would oversubscribe the session slot budget. It is a capacity guard against launching more concurrent sessions than cfg.max_parallel_sessions allows.

Solutions

1. Increase cfg.max_parallel_sessions so it covers live sessions plus the template's step count
2. Complete, cancel, or clean up currently live sessions to free slots before launching
3. Split the template into smaller templates with fewer steps and launch them sequentially
4. Check for stale/orphaned sessions inflating the live count and remove them

Example fix

// before
anyhow::bail!(
    "template {template_name} requires {} session slots but only {available_slots} available",
    template.steps.len()
);
// after: guard before launching, or raise the limit
let available_slots = cfg.max_parallel_sessions.saturating_sub(live_sessions);
if template.steps.len() > available_slots {
    eprintln!("waiting for slots... need {}, have {}", template.steps.len(), available_slots);
    return Ok(None); // or reduce template steps
}

let live = count_live_sessions(db);
if template.steps.len() > cfg.max_parallel_sessions.saturating_sub(live) {
    return Err(format!("need {} slots, have {}", template.steps.len(), cfg.max_parallel_sessions - live));
}

When it happens

Trigger: Calling launch_orchestration_template with a template whose steps.len() > available_slots, where available_slots = max_parallel_sessions - count of live sessions (states not Pending/Stale counted as live via the preceding filter).

Common situations: Running a large orchestration template (many steps) while many sessions are already active; max_parallel_sessions configured too low for the template size; zombie/Idle sessions counted as live so slots appear exhausted; trying to launch multiple templates concurrently and hitting the shared slot pool.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• orchestration template
• agent profile inheritance cycle
• An install config path is required
• application config exceeds local size limit
• Asset request_id/modality does not match the bundle

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/72daf543f3a87dfa. Report an issue: GitHub.

Appendix: 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 8321021c54)