huggingface/smolagents · error · ValueError

Missing API key. Make sure you have 'EXA_API_KEY' in your en

Error message

Missing API key. Make sure you have 'EXA_API_KEY' in your env variables.

What it means

Raised by SearchEngineTool.search_exa when the EXA_API_KEY environment variable is unset or empty. The key is read lazily at search time (not construction), so a tool built without a key fails only when an Exa search is actually executed.

Source

Thrown at src/smolagents/default_tools.py:463

        results = [
            {
                "title": item.findtext("title"),
                "link": item.findtext("link"),
                "description": item.findtext("description"),
            }
            for item in items[: self.max_results]
        ]
        return results

    def search_exa(self, query: str) -> list:
        """Search using the Exa API. Requires an EXA_API_KEY environment variable."""
        import os

        import requests

        api_key = os.getenv("EXA_API_KEY")
        if not api_key:
            raise ValueError("Missing API key. Make sure you have 'EXA_API_KEY' in your env variables.")

        response = requests.post(
            "https://api.exa.ai/search",
            headers={
                "x-api-key": api_key,
                "Content-Type": "application/json",
                "x-exa-integration": "smolagents",
            },
            json={
                "query": query,
                "numResults": self.max_results,
                "contents": {"highlights": True},
            },
            timeout=getattr(self, "timeout", 30),
        )
        response.raise_for_status()
        data = response.json()
        return [

View on GitHub (pinned to 30bb116109)

Solutions

export EXA_API_KEY=... (get one at exa.ai) before running, and load .env files before tool use.
If using dotenv, ensure load_dotenv() executes before the first search call.
Verify with os.getenv('EXA_API_KEY') in the failing process.

Example fix

# before
tool = SearchEngineTool(engine='exa'); tool.run('x')  # ValueError at search time
# after
import os
os.environ['EXA_API_KEY'] = '...'
tool.run('x')

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.getenv('EXA_API_KEY'): raise SystemExit('set EXA_API_KEY before using engine=exa')

Prevention

Remember the key is checked at search time, not construction — validate early yourself.
Keep per-engine keys in one env-loading module.

When it happens

Trigger: SearchEngineTool(engine='exa') with no EXA_API_KEY in env, then calling run/search. Also fails when the var exists but is an empty string, since the check is `if not api_key`.

Common situations: Missing .env loading in notebooks/containers, keys set in the deployment shell but not in the app process, or forgetting that the exa path needs its own key separate from serper/serpapi keys.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/dfae8b438537ec9e. Report an issue: GitHub.