Panniantong/Agent-Reach · error · TranscribeError

allow_provider_fallback requires provider='auto'

Error message

allow_provider_fallback requires provider='auto'

What it means

Raised by transcribe() (transcribe.py:421-424) when allow_provider_fallback=True is combined with an explicit provider. Fallback means 'on chunk failure, try the next configured provider', which only has meaning in auto mode where multiple candidates exist; with a single pinned provider the flag would silently do nothing, so it is rejected as an API contract check.

Source

Thrown at agent_reach/transcribe.py:422

def transcribe(
    source: str,
    *,
    provider: str = "auto",
    out_dir: Optional[Path] = None,
    config: Optional[Config] = None,
    allow_provider_fallback: bool = False,
) -> str:
    """Transcribe a URL or local file path. Returns the joined transcript text.

    `provider` is one of `auto`, `groq`, or `openai`. Auto mode selects the
    first configured provider (Groq, then OpenAI). In auto mode only, set
    `allow_provider_fallback=True` to permit sending failed chunks to the next
    configured provider; using the flag with an explicit provider is rejected.
    `out_dir` defaults to a fresh temp directory; intermediate files stay there.
    """
    if allow_provider_fallback and provider != "auto":
        raise TranscribeError(
            "allow_provider_fallback requires provider='auto'"
        )
    cfg = config or Config()
    candidates = _provider_order(provider)
    configured = [p for p in candidates if _provider_key(p, cfg)]

    # Validate at least one provider is configured before doing expensive work.
    if not configured:
        names = ", ".join(PROVIDERS[p]["key_field"] for p in candidates)
        raise NoProviderConfigured(f"no provider key configured (need one of: {names})")

    order = configured
    if provider == "auto" and not allow_provider_fallback:
        order = configured[:1]

    if out_dir:
        return _transcribe_in_dir(source, order, cfg, Path(out_dir))

View on GitHub (pinned to 93ae1d18c3)

Solutions

1. Drop the flag when pinning a provider: transcribe(url, provider='groq')
2. Or switch to auto: transcribe(url, provider='auto', allow_provider_fallback=True)
3. If resilience is the goal, remember fallback only helps when BOTH providers have keys configured — run agent-reach configure for each

Example fix

# before
text = transcribe(url, provider="groq", allow_provider_fallback=True)  # raises

# after — pick one:
text = transcribe(url, provider="groq")  # pinned, no fallback
text = transcribe(url, provider="auto", allow_provider_fallback=True)  # auto with fallback

def fallback_flag_valid(provider: str, allow_provider_fallback: bool) -> bool:
    return not allow_provider_fallback or provider == "auto"

from agent_reach.transcribe import TranscribeError
try:
    text = transcribe(source, provider=p, allow_provider_fallback=fb)
except TranscribeError as e:
    if "requires provider='auto'" in str(e):
        return transcribe(source, provider="auto", allow_provider_fallback=True)
    raise

When it happens

Trigger: transcribe(url, provider='groq', allow_provider_fallback=True) — raises immediately. The same call with provider='auto' is the supported combination and yields order = all configured providers.

Common situations: Callers copying the fallback flag into every call site for 'resilience' without adjusting provider; refactoring from auto to a pinned provider but keeping the flag; IDE autocomplete inserting the kwarg.

Related errors

• unknown provider: {provider}
• unknown provider: {provider} (use groq|openai|auto)
• audio duration exceeds safety limit of {max_minutes} minutes
• chunk segment duration must be positive
• {provider}: missing {PROVIDERS[provider]['key_field']} (conf

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