affaan-m/ECC · error

Unknown orchestration template: {name}

Error message

Unknown orchestration template: {name}

What it means

Runtime error from Config::resolve_orchestration_template in ecc2/src/config/mod.rs. The method looks up the requested template name in self.orchestration_templates; if the key is absent, it bails with "Unknown orchestration template: {name}". The name is interpolated as-is into the message, so a misspelled or unloaded template name is the direct cause.

Source

Thrown at ecc2/src/config/mod.rs:400

    pub fn resolve_agent_profile(&self, name: &str) -> Result<ResolvedAgentProfile> {
        let mut chain = Vec::new();
        self.resolve_agent_profile_inner(name, &mut chain)
    }

    pub fn harness_runner(&self, harness: &str) -> Option<&HarnessRunnerConfig> {
        let key = harness.trim().to_ascii_lowercase();
        self.harness_runners.get(&key)
    }

    pub fn resolve_orchestration_template(
        &self,
        name: &str,
        vars: &BTreeMap<String, String>,
    ) -> Result<ResolvedOrchestrationTemplate> {
        let template = self
            .orchestration_templates
            .get(name)
            .ok_or_else(|| anyhow::anyhow!("Unknown orchestration template: {name}"))?;

        if template.steps.is_empty() {
            anyhow::bail!("orchestration template {name} has no steps");
        }

        let description = interpolate_optional_string(template.description.as_deref(), vars)?;
        let project = interpolate_optional_string(template.project.as_deref(), vars)?;
        let task_group = interpolate_optional_string(template.task_group.as_deref(), vars)?;
        let default_agent = interpolate_optional_string(template.agent.as_deref(), vars)?;
        let default_profile = interpolate_optional_string(template.profile.as_deref(), vars)?;
        if let Some(profile_name) = default_profile.as_deref() {
            self.resolve_agent_profile(profile_name)?;
        }

        let mut steps = Vec::with_capacity(template.steps.len());
        for (index, step) in template.steps.iter().enumerate() {
            let task = interpolate_required_string(&step.task, vars).with_context(|| {
                format!(

View on GitHub (pinned to 01e15490f0)

Solutions

1. Dump the available template names (config introspection command or by inspecting the loaded config) and copy the exact key.
2. Confirm the config file that defines the template is on the load path and parses without warnings.
3. Match casing exactly; treat template names as case-sensitive.
4. If the template is new, add it under the orchestration_templates section with at least one step.

Example fix

// before
let resolved = cfg.resolve_orchestration_template("deploy", &vars)?;

// after
let name = "deploy_prod"; // exact key from config
if !cfg.known_templates().contains(&name) {
    anyhow::bail!("template {name} not registered; available: {:?}", cfg.known_templates());
}
let resolved = cfg.resolve_orchestration_template(name, &vars)?;

// Before resolving, confirm the template is registered.
let known: HashSet<String> = cfg.known_templates();
if !known.contains(name) {
    eprintln!("template {name} not found; available: {:?}", known);
    return Ok(());
}
let resolved = cfg.resolve_orchestration_template(name, &vars)?;

fn template_exists(cfg: &Config, name: &str) -> bool {
    cfg.known_templates().contains(name)
}

match cfg.resolve_orchestration_template(name, &vars) {
    Ok(t) => t,
    Err(e) if e.to_string().contains("Unknown orchestration template") => {
        eprintln!("tip: known templates: {:?}", cfg.known_templates());
        return Err(e);
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling resolve_orchestration_template(name, vars) with a `name` that is not a key in the loaded orchestration_templates map. This happens when a command/plan references a template that the loaded config files never defined, or when the casing of the name does not match.

Common situations: Typo in the template name on the CLI or in a plan file; the template is defined in a config file that was not included in the load path; the template was renamed but references were not updated; case mismatch ("Deploy" vs "deploy") since lookups are exact.

Related errors

• orchestration template {name} has no steps
• Unknown agent profile: {name}
• missing orchestration template variable(s): {}
• --config-dir must be an existing absolute directory.
• invalid qualification configuration

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