crewAIInc/crewAI · error · ValueError

Missing API key, you can get the key from https://serpapi.co

Error message

Missing API key, you can get the key from https://serpapi.com/manage-api-key

What it means

ValueError raised by the SerpApi base tool during initialization when the SERPAPI_API_KEY environment variable is unset or empty. The tool exclusively reads the key from the environment (os.getenv) — there is no constructor parameter — and fails fast with a pointer to the SerpApi key-management page rather than sending unauthenticated requests. It fires right after the serpapi import succeeds.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/serpapi_tool/serpapi_base_tool.py:46

        try:
            from serpapi import Client
        except ImportError:
            import click

            if click.confirm(
                "You are missing the 'serpapi' package. Would you like to install it?"
            ):
                import subprocess

                subprocess.run(["uv", "add", "serpapi"], check=True)  # noqa: S607
                from serpapi import Client  # type: ignore[import-untyped]
            else:
                raise ImportError(
                    "`serpapi` package not found, please install with `uv add serpapi`"
                ) from None
        api_key = os.getenv("SERPAPI_API_KEY")
        if not api_key:
            raise ValueError(
                "Missing API key, you can get the key from https://serpapi.com/manage-api-key"
            )
        self.client = Client(api_key=api_key)

    def _omit_fields(
        self, data: dict[str, Any] | list[Any], omit_patterns: list[str]
    ) -> None:
        if isinstance(data, dict):
            for field in list(data.keys()):
                if any(re.compile(p).match(field) for p in omit_patterns):
                    data.pop(field, None)
                else:
                    if isinstance(data[field], (dict, list)):
                        self._omit_fields(data[field], omit_patterns)
        elif isinstance(data, list):
            for item in data:
                self._omit_fields(item, omit_patterns)

View on GitHub (pinned to 754d7323be)

Solutions

Set the variable: export SERPAPI_API_KEY=... (shell), add it to .env with dotenv loaded, or pass -e SERPAPI_API_KEY=... to docker run.
Verify the exact variable name — only SERPAPI_API_KEY (from https://serpapi.com/manage-api-key) is read.
Add a startup assertion in your app: if not os.getenv('SERPAPI_API_KEY'): fail with a clear config message before building crews.

Example fix

# before
tool = SerpApiGoogleSearchTool()  # ValueError: Missing API key

# after
import os
from dotenv import load_dotenv
load_dotenv()  # .env contains SERPAPI_API_KEY=...
assert os.getenv("SERPAPI_API_KEY"), "SERPAPI_API_KEY not configured"
tool = SerpApiGoogleSearchTool()

Defensive patterns

Strategy: validation

Validate before calling

import os

if not os.getenv("SERPAPI_API_KEY"):
    raise RuntimeError("SERPAPI_API_KEY is not set — get one at https://serpapi.com/manage-api-key")
tool = SerpApiGoogleSearchTool()

Try / catch

try:
    tool = SerpApiGoogleSearchTool()
except ValueError as e:
    if "API key" in str(e):
        raise SystemExit("Configure SERPAPI_API_KEY in the environment (or .env) and rerun") from e
    raise

Prevention

The tool reads only the SERPAPI_API_KEY env var — name it exactly, load .env explicitly.
Pass the key explicitly in CI/Docker: -e SERPAPI_API_KEY=... / secret mount.
Assert required env vars at process startup so misconfig fails before work begins.

When it happens

Trigger: Constructing any SerpApi tool with SERPAPI_API_KEY absent from the environment: not exported in the shell, missing from .env (or python-dotenv not loaded), or empty string.

Common situations: Forgetting to export the key in CI/cron/Docker (`docker run` without -e); .env file present but never loaded into the process; key defined under a different name (SERP_API_KEY, SERPAPI_KEY); new machine/deployment where secrets were never provisioned.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/1f4da499b89ce5cc. Report an issue: GitHub.