zeroclaw-labs/zeroclaw · error

transcription.max_audio_bytes must be greater than zero

Error message

transcription.max_audio_bytes must be greater than zero

What it means

TranscriptionManager::new() rejects a TranscriptionConfig where max_audio_bytes is Some(0). Zero is treated as a misconfiguration, not as 'unlimited' — to have no global limit, the key must be absent (None). The check runs before any provider registration, so the manager is never constructed with this value.

Source

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

impl TranscriptionManager {
    /// Empty manager with no providers. Used as a base when only typed
    /// `[providers.transcription.<family>.<alias>]` config is present and
    /// there is no legacy `[transcription]` block to seed from.
    pub fn empty() -> Self {
        Self {
            transcription_providers: HashMap::new(),
            max_audio_bytes: None,
            agent_transcription_provider: String::new(),
        }
    }

    /// Build a `TranscriptionManager` from a `TranscriptionConfig`. The
    /// resolved agent alias starts empty; orchestrators that wire the
    /// manager to a specific agent should call
    /// `with_agent_transcription_provider` to set it.
    pub fn new(config: &TranscriptionConfig) -> Result<Self> {
        if matches!(config.max_audio_bytes, Some(0)) {
            bail!("transcription.max_audio_bytes must be greater than zero");
        }

        let mut transcription_providers: HashMap<String, Box<dyn TranscriptionProvider>> =
            HashMap::new();

        Self::register_legacy_providers(&mut transcription_providers, config);

        if config.enabled && transcription_providers.is_empty() {
            bail!(
                "Transcription is enabled but no transcription provider registered \
                 successfully. Configure at least one of: [transcription] (Groq) \
                 with api_key + api_url; [transcription.openai]; [transcription.deepgram]; \
                 [transcription.assemblyai]; [transcription.google]; [transcription.local_whisper]; \
                 or [providers.transcription.<type>.<alias>]."
            );
        }

        Ok(Self {

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Remove the transcription.max_audio_bytes key entirely to disable the global limit
2. Or set it to the intended positive byte value, e.g. 26214400 (25 MB)

Example fix

# before
[transcription]
enabled = true
max_audio_bytes = 0

# after (no global limit)
[transcription]
enabled = true

// Validate before constructing the manager
fn transcription_config_ok(cfg: &TranscriptionConfig) -> bool {
    !matches!(cfg.max_audio_bytes, Some(0))
}

fn transcription_config_ok(cfg: &TranscriptionConfig) -> bool {
    !matches!(cfg.max_audio_bytes, Some(0))
}

When it happens

Trigger: Constructing TranscriptionManager::new(&config) with zeroclaw.toml containing transcription.max_audio_bytes = 0.

Common situations: A user writes max_audio_bytes = 0 intending 'no limit' or 'disabled'; a templating/env substitution produces 0 when the variable is unset; copying an example config that used 0 as a placeholder.

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

• matrix: `homeserver` is required
• Transcription is enabled but no transcription provider regis
• Transcription is enabled but no transcription provider regis
• Cannot persist empty Telegram identity
• Audio file too large ({} bytes, max {MAX_AUDIO_BYTES})

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