crewAIInc/crewAI · error · ValueError

OPENAI_API_KEY environment variable is required for Weaviate

Error message

OPENAI_API_KEY environment variable is required for WeaviateVectorSearchTool and it is mandatory to use the tool.

What it means

WeaviateVectorSearchTool embeds queries with OpenAI via Weaviate's vectorizer, which requires an OpenAI API key passed as the X-OpenAI-Api-Key header. At construction time (only when weaviate-client is importable) it reads OPENAI_API_KEY from the environment and raises ValueError if it is unset or empty.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/weaviate_tool/vector_search.py:91

                required=True,
            ),
        ]
    )
    weaviate_cluster_url: str = Field(
        ...,
        description="The URL of the Weaviate cluster",
    )
    weaviate_api_key: str = Field(
        ...,
        description="The API key for the Weaviate cluster",
    )

    def __init__(self, **kwargs: Any) -> None:
        super().__init__(**kwargs)
        if WEAVIATE_AVAILABLE:
            openai_api_key = os.environ.get("OPENAI_API_KEY")
            if not openai_api_key:
                raise ValueError(
                    "OPENAI_API_KEY environment variable is required for WeaviateVectorSearchTool and it is mandatory to use the tool."
                )
            self.headers = {"X-OpenAI-Api-Key": openai_api_key}
        else:
            if click.confirm(
                "You are missing the 'weaviate-client' package. Would you like to install it?"
            ):
                subprocess.run(["uv", "pip", "install", "weaviate-client"], check=True)  # noqa: S607

            else:
                raise ImportError(
                    "You are missing the 'weaviate-client' package. Would you like to install it?"
                )

    def _run(self, query: str) -> str:
        if not WEAVIATE_AVAILABLE:
            raise ImportError(
                "You are missing the 'weaviate-client' package. Would you like to install it?"

View on GitHub (pinned to 754d7323be)

Solutions

Export OPENAI_API_KEY before creating the tool: export OPENAI_API_KEY=sk-... or set it in your environment/secrets manager.
Call load_dotenv() at the very top of the entrypoint, before any tool is built.
Add a startup assertion for all three required vars (OPENAI_API_KEY, WEAVIATE_URL, WEAVIATE_API_KEY) to fail fast with a clear message.

Example fix

# before
tool = WeaviateVectorSearchTool(
    weaviate_cluster_url='https://x.weaviate.network',
    weaviate_api_key='...',
)  # ValueError: OPENAI_API_KEY required

# after
import os
from dotenv import load_dotenv
load_dotenv()
assert os.getenv('OPENAI_API_KEY'), 'set OPENAI_API_KEY'
tool = WeaviateVectorSearchTool(
    weaviate_cluster_url='https://x.weaviate.network',
    weaviate_api_key='...',
)

Defensive patterns

Strategy: validation

Validate before calling

import os

missing = [v for v in ('OPENAI_API_KEY',) if not os.environ.get(v)]
if missing:
    raise SystemExit(f'missing env vars: {missing}')
# WeaviateVectorSearchTool can now be constructed safely

Try / catch

try:
    tool = WeaviateVectorSearchTool(
        weaviate_cluster_url=URL, weaviate_api_key=WKEY
    )
except ValueError as e:
    if 'OPENAI_API_KEY' in str(e):
        raise SystemExit('Set OPENAI_API_KEY - required for embeddings')
    raise

Prevention

Load .env at the very top of the entrypoint, before tool imports run.
Assert all required env vars (OPENAI, WEAVIATE) at startup with clear messages.
Manage secrets via the platform's secret store, not ad-hoc exports.

When it happens

Trigger: Instantiating WeaviateVectorSearchTool(weaviate_cluster_url=..., weaviate_api_key=...) without OPENAI_API_KEY in os.environ, or with it set to an empty string.

Common situations: Only configuring Weaviate credentials and forgetting the OpenAI key; .env loaded after tool construction; CI/production secrets not injected; key named differently (e.g., OPEN_AI_API_KEY).

Related errors

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