{"record":{"id":"db0d65398a435c5c","repo":"Panniantong/Agent-Reach","slug":"allow-provider-fallback-requires-provider-auto","errorCode":null,"errorMessage":"allow_provider_fallback requires provider='auto'","messagePattern":"allow_provider_fallback requires provider='auto'","errorType":"exception","errorClass":"TranscribeError","httpStatus":null,"severity":"error","filePath":"agent_reach/transcribe.py","lineNumber":422,"sourceCode":"\ndef transcribe(\n    source: str,\n    *,\n    provider: str = \"auto\",\n    out_dir: Optional[Path] = None,\n    config: Optional[Config] = None,\n    allow_provider_fallback: bool = False,\n) -> str:\n    \"\"\"Transcribe a URL or local file path. Returns the joined transcript text.\n\n    `provider` is one of `auto`, `groq`, or `openai`. Auto mode selects the\n    first configured provider (Groq, then OpenAI). In auto mode only, set\n    `allow_provider_fallback=True` to permit sending failed chunks to the next\n    configured provider; using the flag with an explicit provider is rejected.\n    `out_dir` defaults to a fresh temp directory; intermediate files stay there.\n    \"\"\"\n    if allow_provider_fallback and provider != \"auto\":\n        raise TranscribeError(\n            \"allow_provider_fallback requires provider='auto'\"\n        )\n    cfg = config or Config()\n    candidates = _provider_order(provider)\n    configured = [p for p in candidates if _provider_key(p, cfg)]\n\n    # Validate at least one provider is configured before doing expensive work.\n    if not configured:\n        names = \", \".join(PROVIDERS[p][\"key_field\"] for p in candidates)\n        raise NoProviderConfigured(f\"no provider key configured (need one of: {names})\")\n\n    order = configured\n    if provider == \"auto\" and not allow_provider_fallback:\n        order = configured[:1]\n\n    if out_dir:\n        return _transcribe_in_dir(source, order, cfg, Path(out_dir))\n","sourceCodeStart":404,"sourceCodeEnd":440,"githubUrl":"https://github.com/Panniantong/Agent-Reach/blob/93ae1d18c37b707dec053c7c4f9d91cd8ef8943d/agent_reach/transcribe.py#L404-L440","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Drop the flag when pinning a provider: transcribe(url, provider='groq')","Or switch to auto: transcribe(url, provider='auto', allow_provider_fallback=True)","If resilience is the goal, remember fallback only helps when BOTH providers have keys configured — run agent-reach configure for each"],"exampleFix":"# before\ntext = transcribe(url, provider=\"groq\", allow_provider_fallback=True)  # raises\n\n# after — pick one:\ntext = transcribe(url, provider=\"groq\")  # pinned, no fallback\ntext = transcribe(url, provider=\"auto\", allow_provider_fallback=True)  # auto with fallback","handlingStrategy":"validation","validationCode":"def fallback_flag_valid(provider: str, allow_provider_fallback: bool) -> bool:\n    return not allow_provider_fallback or provider == \"auto\"","typeGuard":null,"tryCatchPattern":"from agent_reach.transcribe import TranscribeError\ntry:\n    text = transcribe(source, provider=p, allow_provider_fallback=fb)\nexcept TranscribeError as e:\n    if \"requires provider='auto'\" in str(e):\n        return transcribe(source, provider=\"auto\", allow_provider_fallback=True)\n    raise","preventionTips":["Treat allow_provider_fallback as auto-mode-only by contract","When pinning a provider, omit the flag entirely","Configure both groq and openai keys so auto+fallback actually has a second candidate"],"tags":["validation","api-misuse","provider","transcription"],"backgroundTag":null,"analyzedSha":"93ae1d18c37b707dec053c7c4f9d91cd8ef8943d","analyzedAt":"2026-08-14T22:54:06.735Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}