Panniantong/Agent-Reach · error · TranscribeError

unknown provider: {provider}

Error message

unknown provider: {provider}

What it means

Raised by transcribe_chunk (transcribe.py:368-370) when the provider argument is not a key of PROVIDERS ({'groq', 'openai'}). transcribe_chunk handles exactly one concrete provider; the 'auto' pseudo-provider is resolved earlier by _provider_order in transcribe() and must never reach this function.

Source

Thrown at agent_reach/transcribe.py:370

    return chunks


def _provider_key(provider: str, config: Config) -> Optional[str]:
    field = PROVIDERS[provider]["key_field"]
    val = config.get(field)
    return val or None


def transcribe_chunk(
    chunk: Path,
    provider: str,
    *,
    config: Optional[Config] = None,
    timeout: int = 120,
) -> str:
    """Transcribe one chunk via the named provider. Raises TranscribeError on failure."""
    if provider not in PROVIDERS:
        raise TranscribeError(f"unknown provider: {provider}")
    cfg = config or Config()
    key = _provider_key(provider, cfg)
    if not key:
        raise NoProviderConfigured(
            f"{provider}: missing {PROVIDERS[provider]['key_field']} "
            f"(configure with `agent-reach configure {provider}-key ...`)"
        )

    info = PROVIDERS[provider]
    with chunk.open("rb") as fh:
        try:
            resp = requests.post(
                info["endpoint"],
                headers={"Authorization": f"Bearer {key}"},
                files={"file": (chunk.name, fh, "audio/m4a")},
                data={"model": info["model"], "response_format": "text"},
                timeout=timeout,
            )

View on GitHub (pinned to 93ae1d18c3)

Solutions

  1. Use a concrete provider: transcribe_chunk(chunk, 'groq') or transcribe_chunk(chunk, 'openai')
  2. For automatic selection, call transcribe(source, provider='auto') which resolves the order before any chunk is sent
  3. If calling from code, validate against agent_reach.transcribe.PROVIDERS.keys() first

Example fix

# before
transcribe_chunk(chunk, provider="auto")  # unknown provider: auto

# after
from agent_reach.transcribe import PROVIDERS
assert provider in PROVIDERS, f"provider must be one of {sorted(PROVIDERS)}"
text = transcribe_chunk(chunk, provider=provider)
Defensive patterns

Strategy: type-guard

Validate before calling

from agent_reach.transcribe import PROVIDERS

def is_concrete_provider(name: str) -> bool:
    return name in PROVIDERS  # {'groq', 'openai'} — 'auto' NOT allowed here

Type guard

from agent_reach.transcribe import PROVIDERS
from typing import Literal

ConcreteProvider = Literal["groq", "openai"]

def is_concrete_provider(name: str) -> bool:
    """Type guard: True when name is a valid single provider for transcribe_chunk."""
    return isinstance(name, str) and name in PROVIDERS

Try / catch

from agent_reach.transcribe import TranscribeError
try:
    text = transcribe_chunk(chunk, provider)
except TranscribeError as e:
    if str(e).startswith("unknown provider"):
        # caller should have used transcribe(..., provider='auto')
        return transcribe(source, provider="auto")
    raise

Prevention

When it happens

Trigger: Direct calls like transcribe_chunk(path, 'deepgram') or transcribe_chunk(path, 'auto') — 'auto' is invalid here because there is nothing to auto-select at chunk level. Valid: 'groq', 'openai'.

Common situations: Calling the internal API directly instead of transcribe(); forwarding a user-supplied provider string without validation; version drift after a provider was renamed or removed from PROVIDERS.

Related errors

AI-assisted analysis of Panniantong/Agent-Reach@93ae1d18c3 (2026-08-14). Data as JSON: /api/errors/60b98b69005ace83. Report an issue: GitHub.