crewAIInc/crewAI · error · ValueError

`api_key` is required, please set the `HYPERBROWSER_API_KEY`

Error message

`api_key` is required, please set the `HYPERBROWSER_API_KEY` environment variable or pass it directly

What it means

ValueError raised in HyperbrowserLoadTool.__init__ when the constructor's api_key argument is falsy. NOTE THE BUG: the guard tests the local parameter 'api_key', not self.api_key (which already merged in HYPERBROWSER_API_KEY from the environment). So even when the env var IS set, omitting the constructor argument still raises — the documented env-variable fallback is unreachable past this line.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/hyperbrowser_load_tool/hyperbrowser_load_tool.py:51

    args_schema: type[BaseModel] = HyperbrowserLoadToolSchema
    api_key: str | None = None
    hyperbrowser: Any | None = None
    package_dependencies: list[str] = Field(default_factory=lambda: ["hyperbrowser"])
    env_vars: list[EnvVar] = Field(
        default_factory=lambda: [
            EnvVar(
                name="HYPERBROWSER_API_KEY",
                description="API key for Hyperbrowser services",
                required=False,
            ),
        ]
    )

    def __init__(self, api_key: str | None = None, **kwargs: Any) -> None:
        super().__init__(**kwargs)
        self.api_key = api_key or os.getenv("HYPERBROWSER_API_KEY")
        if not api_key:
            raise ValueError(
                "`api_key` is required, please set the `HYPERBROWSER_API_KEY` environment variable or pass it directly"
            )

        try:
            from hyperbrowser import Hyperbrowser  # type: ignore[import-untyped]
        except ImportError as e:
            raise ImportError(
                "`hyperbrowser` package not found, please run `pip install hyperbrowser`"
            ) from e

        if not self.api_key:
            raise ValueError(
                "HYPERBROWSER_API_KEY is not set. Please provide it either via the constructor with the `api_key` argument or by setting the HYPERBROWSER_API_KEY environment variable."
            )

        self.hyperbrowser = Hyperbrowser(api_key=self.api_key)

    @staticmethod

View on GitHub (pinned to 754d7323be)

Solutions

Pass the key explicitly: HyperbrowserLoadTool(api_key=os.environ['HYPERBROWSER_API_KEY']).
Or fix the library guard: change 'if not api_key:' to 'if not self.api_key:' so the env-var fallback works.
Double-check the env var name spelling (HYPERBROWSER_API_KEY) if you patch the guard.

Example fix

# before
os.environ['HYPERBROWSER_API_KEY'] = 'hb_...'
tool = HyperbrowserLoadTool()  # raises: guard checks the param, not self.api_key

# after
tool = HyperbrowserLoadTool(api_key=os.environ['HYPERBROWSER_API_KEY'])

# library fix:
- if not api_key:
+ if not self.api_key:

Defensive patterns

Strategy: validation

Validate before calling

api_key = os.getenv('HYPERBROWSER_API_KEY')
if not api_key:
    raise SystemExit('set HYPERBROWSER_API_KEY or pass api_key=')
tool = HyperbrowserLoadTool(api_key=api_key)  # pass explicitly; env-only path is buggy

Try / catch

try:
    tool = HyperbrowserLoadTool(api_key=os.getenv('HYPERBROWSER_API_KEY'))
except ValueError as e:
    if 'api_key' in str(e):
        raise SystemExit('provide HYPERBROWSER_API_KEY explicitly') from e
    raise

Prevention

Always pass api_key explicitly to Hyperbrowser tools; do not rely on the env-only path.
If you maintain a fork, fix the guard to check self.api_key instead of the parameter.
Validate required secrets at app startup, not at tool call time.

When it happens

Trigger: Calling HyperbrowserLoadTool() with no api_key argument, relying on the HYPERBROWSER_API_KEY environment variable as the docs suggest — this raises despite the env var being set. Only an explicit api_key='...' (or a truthy env var AND... no, the check ignores self.api_key entirely) passes; actually any falsy constructor arg triggers it.

Common situations: Users following the EnvVar description and setting HYPERBROWSER_API_KEY in .env, then instantiating with no args and hitting a spurious error; deployments that inject secrets exclusively via environment variables.

Related errors

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