zeroclaw-labs/zeroclaw · error

Agent has no transcription_provider configured. Set `agent.<

Error message

Agent has no transcription_provider configured. Set `agent.<alias>.transcription_provider = "<type>.<alias>"` referencing a configured transcription provider.

What it means

TranscriptionManager::transcribe() dispatches to the agent-resolved provider alias stored in agent_transcription_provider, and that alias is empty. There is deliberately no global default: from_config_for_agent() resolves it from agent.<alias>.transcription_provider, and an unset/missing agent or empty field leaves it empty. The manager also exposes transcribe_with_provider() to bypass the agent binding explicitly.

Source

Thrown at crates/zeroclaw-channels/src/transcription.rs:1128

        self
    }

    /// Set the resolved agent `transcription_provider` alias. Called by
    /// orchestrators that bind this manager to a specific agent at startup.
    /// Subsequent `transcribe` calls dispatch to this alias.
    #[must_use]
    pub fn with_agent_transcription_provider(mut self, alias: impl Into<String>) -> Self {
        self.agent_transcription_provider = alias.into();
        self
    }

    /// Transcribe audio using the runtime-active agent's resolved
    /// `transcription_provider`. Fails loud when the agent has no
    /// transcription_provider configured — there is no global default.
    pub async fn transcribe(&self, audio_data: &[u8], file_name: &str) -> Result<String> {
        let provider_alias = self.agent_transcription_provider.as_str();
        if provider_alias.is_empty() {
            bail!(
                "Agent has no transcription_provider configured. Set \
                 `agent.<alias>.transcription_provider = \"<type>.<alias>\"` \
                 referencing a configured transcription provider."
            );
        }
        self.transcribe_with_provider(audio_data, file_name, provider_alias)
            .await
    }

    /// Transcribe audio using a specific named transcription_provider.
    pub async fn transcribe_with_provider(
        &self,
        audio_data: &[u8],
        file_name: &str,
        transcription_provider: &str,
    ) -> Result<String> {
        let p = self.transcription_providers.get(transcription_provider).ok_or_else(|| {
            let available: Vec<&str> = self.transcription_providers.keys().map(|k| k.as_str()).collect();

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Set the per-agent key: agent.<alias>.transcription_provider = "groq" (legacy name) or "<type>.<alias>" (typed, e.g. "openai.main")
2. Verify the agent alias actually exists in [agents] — a typo means resolution silently yields empty
3. In code that cannot rely on agent binding, call transcribe_with_provider(&audio, name, alias) with a name from available_providers()

Example fix

# before
[transcription]
enabled = true
api_key = "gsk_..."
api_url = "https://api.groq.com/openai/v1/audio/transcriptions"

[agents.main]
# no transcription_provider -> transcribe() errors

# after
[agents.main]
transcription_provider = "groq"

// At startup, verify the agent binding before serving traffic
fn agent_provider_configured(cfg: &Config, alias: &str) -> bool {
    cfg.agents.get(alias)
        .map(|a| !a.transcription_provider.is_empty())
        .unwrap_or(false)
}

fn agent_provider_configured(cfg: &Config, alias: &str) -> bool {
    cfg.agents.get(alias)
        .map(|a| !a.transcription_provider.is_empty())
        .unwrap_or(false)
}

match manager.transcribe(&audio, name).await {
    Ok(text) => Some(text),
    Err(e) if e.to_string().contains("no transcription_provider configured") => {
        tracing::error!("agent transcription_provider not set; configure agent.<alias>.transcription_provider");
        None // or fall back to transcribe_with_provider with a known alias
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: transcribe() called when the resolved agent alias is empty: the runtime agent alias is not set or not found in [agents], the agent block exists but transcription_provider is unset/empty, or the manager was built via new()/empty() and nobody called with_agent_transcription_provider().

Common situations: Agent defined in config with a provider block configured globally but the per-agent transcription_provider key forgotten; default agent alias resolution returning a name absent from [agents]; orchestrator constructing the manager with new() and forgetting to bind the agent's provider.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• Transcription is enabled but no transcription provider regis
• Transcription is enabled but no transcription provider regis
• Audio file too large ({} bytes, local_whisper max {})
• transcription.max_audio_bytes must be greater than zero
• Audio file too large ({} bytes, global max {})

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/58e6489d9ad18afc. Report an issue: GitHub.