ValueError: SERPER_API_KEY not set
crewai.tools.SerperDevTool initialization error: ValueError raised when SERPER_API_KEY environment variable is missing
Stack trace
Traceback (most recent call last):
File "main.py", line 12, in <module>
search_tool = SerperDevTool()
File "/path/to/site-packages/crewai/tools/serper_dev_tool.py", line 45, in __init__
raise ValueError("SERPER_API_KEY not set. Please set the SERPER_API_KEY environment variable.")
ValueError: SERPER_API_KEY not set. Please set the SERPER_API_KEY environment variable. Why it happens
SerperDevTool is a web search integration that requires authentication with Serper.dev's API. The tool's __init__ method explicitly checks for the SERPER_API_KEY environment variable and raises ValueError if it's not found, empty, or None. This is a deliberate safety check to prevent runtime failures when the agent attempts search queries without valid credentials.
Detection
Catch ValueError during agent/tool initialization with a try/except block, or validate environment variables before instantiating any CrewAI tools that require API keys. Add a startup health check that iterates required env vars and logs missing ones before agents run.
Causes & fixes
SERPER_API_KEY environment variable not set in shell, .env file, or deployment environment
Set SERPER_API_KEY in your .env file (SERPER_API_KEY=your_key_here), then load it with python-dotenv: from dotenv import load_dotenv; load_dotenv(). Or set it in your deployment platform's secrets manager (GitHub Actions, Docker, AWS Lambda, etc.).
SERPER_API_KEY is set but os.environ['SERPER_API_KEY'] is called before .env file is loaded
Call load_dotenv() from python-dotenv at the very top of your main script BEFORE importing or instantiating any CrewAI tools. Place it before any tool or agent initialization.
Using os.environ.get('SERPER_API_KEY') without a fallback, then passing empty string or None to SerperDevTool
SerperDevTool does not accept a key parameter: it reads directly from os.environ. Ensure the env var is set before tool initialization, not passed as an argument.
Running CrewAI script in a different shell or environment context where SERPER_API_KEY was not exported
Export the variable before running: export SERPER_API_KEY='your-key' && python main.py (Linux/Mac), or set SERPER_API_KEY=your-key && python main.py (Windows PowerShell)
Code: broken vs fixed
import os
from crewai import Agent, Task, Crew
from crewai.tools import SerperDevTool
# BUG: SerperDevTool initialized WITHOUT checking if SERPER_API_KEY is set
search_tool = SerperDevTool() # This line will raise ValueError
agent = Agent(
role="Research Analyst",
goal="Search for information",
tools=[search_tool]
)
print("Agent created") # Never reaches hereimport os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew
from crewai.tools import SerperDevTool
# FIX: Load .env file FIRST, then check if SERPER_API_KEY is set
load_dotenv()
if not os.environ.get('SERPER_API_KEY'):
raise ValueError(
"SERPER_API_KEY environment variable is not set. "
"Please add it to your .env file or system environment."
)
search_tool = SerperDevTool() # Now safe — SERPER_API_KEY is loaded
agent = Agent(
role="Research Analyst",
goal="Search for information",
tools=[search_tool]
)
print(f"Agent created successfully with search tool")Workaround
If you cannot set environment variables in your current environment, temporarily hardcode the key directly by modifying CrewAI's tool instantiation (though not recommended for production). Alternatively, create a wrapper function that accepts the key as a parameter and sets os.environ['SERPER_API_KEY'] = key before importing SerperDevTool, then instantiate: os.environ['SERPER_API_KEY'] = your_key; search_tool = SerperDevTool(). This only works if you control where the key comes from (e.g., a secure config service).
Prevention
Adopt a startup validation pattern: create a function that checks all required API keys (SERPER_API_KEY, OPENAI_API_KEY, etc.) on app launch, before any agents or tasks run. Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, GitHub Secrets) in production instead of .env files. For local development, version-control a .env.example file with placeholder values and require developers to copy and fill it. Add unit tests that mock SerperDevTool to catch missing env vars in CI/CD before deployment.