NousResearch/hermes-agent · critical · RuntimeError

Provider '{_explicit}' is set in config.yaml but no API key

Error message

Provider '{_explicit}' is set in config.yaml but no API key was found. Set the {_env_hint} environment variable, or switch to a different provider with `hermes model`.

What it means

Raised during AIAgent init when config.yaml names an explicit provider (the `_explicit` value) but no API key for it could be resolved anywhere: the provider-fallback resolution loop finished with _fb_resolved still False. This is a pure configuration error — the provider is selected, its credential is not.

Source

Thrown at agent/agent_init.py:1352

                            agent.model = _fb_model or _fb["model"]
                            agent._fallback_activated = True
                            client_kwargs = {
                                "api_key": _fb_client.api_key,
                                "base_url": str(_fb_client.base_url),
                            }
                            if _provider_timeout is not None:
                                client_kwargs["timeout"] = _provider_timeout
                            _fb_headers = getattr(_fb_client, "_custom_headers", None)
                            if not _fb_headers:
                                _fb_headers = getattr(_fb_client, "default_headers", None)
                            if not _fb_headers:
                                _fb_headers = getattr(_fb_client, "_default_headers", None)
                            if _fb_headers:
                                client_kwargs["default_headers"] = dict(_fb_headers)
                            _fb_resolved = True
                            break
                    if not _fb_resolved:
                        raise RuntimeError(
                            f"Provider '{_explicit}' is set in config.yaml but no API key "
                            f"was found. Set the {_env_hint} environment "
                            f"variable, or switch to a different provider with `hermes model`."
                        )
                if not getattr(agent, "_fallback_activated", False):
                    # No provider configured — reject with a clear message.
                    raise RuntimeError(
                        "No LLM provider configured. Run `hermes model` to "
                        "select a provider, or run `hermes setup` for first-time "
                        "configuration."
                    )
        
        agent._client_kwargs = client_kwargs  # stored for rebuilding after interrupt

        # Enable fine-grained tool streaming for Claude on OpenRouter.
        # Without this, Anthropic buffers the entire tool call and goes
        # silent for minutes while thinking — OpenRouter's upstream proxy
        # times out during the silence.  The beta header makes Anthropic

View on GitHub (pinned to c896c09c42)

Solutions

1. Set the provider's API key in ~/.hermes/.env using the exact variable named in the error's env hint
2. Run `hermes model` and switch to a provider whose key you have
3. Run `hermes setup` for guided first-time configuration
4. Verify the key lives in the active profile's HERMES_HOME/.env and the provider name in config.yaml is spelled exactly

Example fix

# ~/.hermes/.env — before
# (no OPENAI_API_KEY line)

# after
OPENAI_API_KEY=sk-...

import os

def provider_key_present(provider: str) -> bool:
    var = f"{provider.upper().replace('-', '_')}_API_KEY"
    return bool(os.environ.get(var))

assert provider_key_present(configured_provider), (
    f"Set {configured_provider.upper()}_API_KEY before starting hermes"
)

try:
    agent = AIAgent(...)
except RuntimeError as e:
    if "no API key was found" in str(e):
        prompt_user_for_key(str(e))  # surface env hint from the message
    else:
        raise

When it happens

Trigger: config.yaml sets model.provider while the matching env var (named by `_env_hint`) is absent from .env/environment, no credential-pool entry supplies a key, and no auxiliary fallback resolves, so every iteration of the fallback-resolution loop fails to build a client.

Common situations: Fresh install where `hermes model` picked a provider but the key was never entered; key deleted from ~/.hermes/.env; provider name typo so the expected env var is never consulted; hermetic CI with credential env vars unset.

Related errors

• No LLM provider configured. Run `hermes model` to select a p
• Failed to initialize OpenAI client: {e}
• switch_model: no base_url resolved for provider '{new_provid
• Gemini native client requires an API key, but none was provi
• Invalid profile name: ${value}

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/422bf90ed84ed46d. Report an issue: GitHub.