huggingface/smolagents · error · ValueError

Missing API key. Make sure you have '{api_key_env_name}' in

Error message

Missing API key. Make sure you have '{api_key_env_name}' in your env variables.

What it means

Raised in SearchEngineTool/__init__ (GoogleSearchTool-style provider tool) when the required API key environment variable (SERPAPI_API_KEY or SERPER_API_KEY, depending on provider) is not set. The tool reads the key at construction time and refuses to build without it.

Source

Thrown at src/smolagents/default_tools.py:188

            "nullable": True,
        },
    }
    output_type = "string"

    def __init__(self, provider: str = "serpapi"):
        super().__init__()
        import os

        self.provider = provider
        if provider == "serpapi":
            self.organic_key = "organic_results"
            api_key_env_name = "SERPAPI_API_KEY"
        else:
            self.organic_key = "organic"
            api_key_env_name = "SERPER_API_KEY"
        self.api_key = os.getenv(api_key_env_name)
        if self.api_key is None:
            raise ValueError(f"Missing API key. Make sure you have '{api_key_env_name}' in your env variables.")

    def forward(self, query: str, filter_year: int | None = None) -> str:
        import requests

        if self.provider == "serpapi":
            params = {
                "q": query,
                "api_key": self.api_key,
                "engine": "google",
                "google_domain": "google.com",
            }
            base_url = "https://serpapi.com/search.json"
        else:
            params = {
                "q": query,
                "api_key": self.api_key,
            }
            base_url = "https://google.serper.dev/search"

View on GitHub (pinned to 30bb116109)

Solutions

1. Set the correct env var for your provider: export SERPAPI_API_KEY=... or export SERPER_API_KEY=....
2. If using python-dotenv, ensure load_dotenv() runs before constructing the tool.
3. Verify with `env | grep -i serp` that the variable is actually in the running process.

Example fix

# before
tool = GoogleSearchTool(provider='serper')  # ValueError
# after
import os; os.environ['SERPER_API_KEY'] = '...'
tool = GoogleSearchTool(provider='serper')

import os
needed = {'serpapi':'SERPAPI_API_KEY','serper':'SERPER_API_KEY'}[provider]
assert os.getenv(needed), f'set {needed}'

When it happens

Trigger: Instantiating the search tool with provider='serpapi' without SERPAPI_API_KEY in env, or provider='serper' without SERPER_API_KEY. Also when the env var is set in a shell but not in the process (e.g. different venv, docker, or cron).

Common situations: Missing .env loading, deploying to containers/cron where env vars aren't propagated, or using the wrong provider's key name.

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

• Missing API key. Make sure you have 'EXA_API_KEY' in your en
• You must install package `ddgs` to run this tool: for instan
• No results found! Try a less restrictive/shorter query.
• No results found for query: '{query}' with filtering on year
• No results found for query: '{query}'. Use a less restrictiv

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