Panniantong/Agent-Reach · error · NoProviderConfigured

no provider key configured (need one of: {names})

Error message

no provider key configured (need one of: {names})

What it means

Raised by transcribe() before any downloading or ffmpeg work when none of the candidate providers has an API key in the active Config. Agent Reach routes Whisper transcription through groq (groq_api_key) or openai (openai_api_key), and it refuses to start expensive audio processing when it cannot possibly finish. It is a subclass of TranscribeError (NoProviderConfigured) so callers can distinguish 'misconfigured' from 'provider failed'.

Source

Thrown at agent_reach/transcribe.py:432

    `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))

    with tempfile.TemporaryDirectory(prefix="transcribe-") as tmp:
        return _transcribe_in_dir(source, order, cfg, Path(tmp))


def _transcribe_in_dir(source: str, order: List[str], cfg: Config, work_dir: Path) -> str:
    work_dir.mkdir(parents=True, exist_ok=True)

    src_path = Path(source)
    if src_path.is_file():
        audio = src_path

View on GitHub (pinned to 93ae1d18c3)

Solutions

  1. Run `python -m agent_reach.cli doctor` to see which provider keys are detected
  2. Set GROQ_API_KEY (preferred, used by whisper-large-v3) or OPENAI_API_KEY in the environment or Agent Reach config
  3. If you passed provider='groq'/'openai' explicitly, verify that specific provider's key field (groq_api_key / openai_api_key) is configured
  4. When constructing Config manually, populate the key before calling transcribe()

Example fix

# before
from agent_reach.transcribe import transcribe
text = transcribe("https://youtube.com/watch?v=x")  # NoProviderConfigured

# after
import os
os.environ.setdefault("GROQ_API_KEY", "gsk_...")
text = transcribe("https://youtube.com/watch?v=x")
Defensive patterns

Strategy: validation

Validate before calling

from agent_reach.transcribe import PROVIDERS, _provider_key
from agent_reach.config import Config

def has_provider_key(provider: str = "auto", cfg: Config | None = None) -> bool:
    cfg = cfg or Config()
    candidates = ["groq", "openai"] if provider == "auto" else [provider]
    return any(_provider_key(p, cfg) for p in candidates)

Type guard

from agent_reach.transcribe import NoProviderConfigured

def is_no_provider(err: BaseException) -> bool:
    return isinstance(err, NoProviderConfigured)

Try / catch

from agent_reach.transcribe import transcribe, NoProviderConfigured
try:
    text = transcribe(url)
except NoProviderConfigured:
    # config problem: fail fast with actionable message, do not retry
    raise SystemExit("Set GROQ_API_KEY or OPENAI_API_KEY before transcribing")

Prevention

When it happens

Trigger: Calling transcribe(source) or transcribe(source, provider='groq') when neither GROQ_API_KEY nor OPENAI_API_KEY is present in the YAML config, env vars, or Config object passed in. Passing provider='openai' with only a Groq key configured also triggers it, because candidates are filtered to the requested provider only.

Common situations: Fresh install where `agent-reach install --env=auto` was never run; CI environment missing the env vars; key present under a different YAML section name so Config does not pick it up; passing a custom Config instance that was built without keys.

Related errors

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