NousResearch/hermes-agent · error · RuntimeError

Gemini native client requires an API key, but none was provi

Error message

Gemini native client requires an API key, but none was provided. Set GOOGLE_API_KEY or GEMINI_API_KEY in your environment / ~/.hermes/.env (get one at https://aistudio.google.com/app/apikey), or run `hermes setup` to configure the Google provider.

What it means

The native Gemini client (GeminiNativeClient in agent/gemini_native_adapter.py) was constructed with an empty or whitespace-only api_key. The client talks to Google's Generative Language API directly, which requires a key on every request, so construction fails fast with instructions on where to get one and how to configure it.

Source

Thrown at agent/gemini_native_adapter.py:970

    def __init__(self, client: "AsyncGeminiNativeClient"):
        self.completions = _AsyncGeminiChatCompletions(client)


class GeminiNativeClient:
    """Minimal OpenAI-SDK-compatible facade over Gemini's native REST API."""

    def __init__(
        self,
        *,
        api_key: str,
        base_url: Optional[str] = None,
        default_headers: Optional[Dict[str, str]] = None,
        timeout: Any = None,
        http_client: Optional[httpx.Client] = None,
        **_: Any,
    ) -> None:
        if not (api_key or "").strip():
            raise RuntimeError(
                "Gemini native client requires an API key, but none was provided. "
                "Set GOOGLE_API_KEY or GEMINI_API_KEY in your environment / ~/.hermes/.env "
                "(get one at https://aistudio.google.com/app/apikey), or run `hermes setup` "
                "to configure the Google provider."
            )
        self.api_key = api_key
        normalized_base = (base_url or DEFAULT_GEMINI_BASE_URL).rstrip("/")
        if normalized_base.endswith("/openai"):
            normalized_base = normalized_base[: -len("/openai")]
        self.base_url = normalized_base
        self._default_headers = dict(default_headers or {})
        self.chat = _GeminiChatNamespace(self)
        self.is_closed = False
        self._http = http_client or httpx.Client(
            timeout=timeout or httpx.Timeout(connect=15.0, read=600.0, write=30.0, pool=30.0)
        )

    def close(self) -> None:

View on GitHub (pinned to c896c09c42)

Solutions

1. Add GOOGLE_API_KEY (or GEMINI_API_KEY) to ~/.hermes/.env — keys are secrets and belong there, not in config.yaml.
2. Or run `hermes setup` and configure the Google provider interactively.
3. Get a key at https://aistudio.google.com/app/apikey if you don't have one.
4. If using profiles, verify the key exists in the active profile's .env (HERMES_HOME scoped).

Example fix

# before — no key configured
# after
echo 'GOOGLE_API_KEY=AIza...' >> ~/.hermes/.env
# or: hermes setup  → choose Google provider

import os

def gemini_key_present() -> bool:
    return bool((os.getenv('GOOGLE_API_KEY') or os.getenv('GEMINI_API_KEY') or '').strip())

try:
    client = GeminiNativeClient(api_key=os.getenv('GOOGLE_API_KEY', ''))
except RuntimeError as e:
    if 'requires an API key' in str(e):
        # add key to ~/.hermes/.env or run hermes setup; then retry
        ...

When it happens

Trigger: Instantiating the native Gemini adapter with api_key='' or None — i.e. neither GOOGLE_API_KEY nor GEMINI_API_KEY is set in the environment or ~/.hermes/.env when the Google provider resolves to native mode.

Common situations: Fresh install without running hermes setup; key present under the wrong variable name; .env not loaded because HERMES_HOME points at a profile that lacks it; key accidentally deleted during config edits.

Related errors

• Provider '{_explicit}' is set in config.yaml but no API key
• Invalid profile name: ${value}
• SSH host is required.
• HERMES_DESKTOP_REMOTE_URL is set but HERMES_DESKTOP_REMOTE_T
• Gateway rejected native login: ${error}${desc ? ` (${desc})`

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