BerriAI/litellm · error · ValueError

OpenAI Moderation: api_key is required. Set OPENAI_API_KEY e

Error message

OpenAI Moderation: api_key is required. Set OPENAI_API_KEY environment variable or pass it in configuration.

What it means

Init-time ValueError from OpenAIModerationGuardrail.__init__: no API key resolved. The guardrail checks the api_key param, then _get_api_key() (which reads OPENAI_API_KEY from the environment and litellm's own key configuration). Since moderations is a paid OpenAI endpoint, the guardrail refuses to construct without credentials.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/openai/moderations.py:81

            **kwargs,
        )

        self.async_handler = get_async_httpx_client(llm_provider=httpxSpecialProvider.GuardrailCallback)

        # Store configuration
        self.api_key = api_key or self._get_api_key()
        self.api_base = api_base or "https://api.openai.com/v1"
        self.model: Literal["omni-moderation-latest", "text-moderation-latest"] = model or "omni-moderation-latest"

        # Read by UnifiedLLMGuardrails.async_post_call_streaming_iterator_hook
        # via getattr(guardrail_to_apply, "streaming_*", default).
        self.streaming_end_of_stream_only: bool = (
            False if streaming_end_of_stream_only is None else streaming_end_of_stream_only
        )
        self.streaming_sampling_rate: int = 5 if streaming_sampling_rate is None else streaming_sampling_rate

        if not self.api_key:
            raise ValueError(
                "OpenAI Moderation: api_key is required. Set OPENAI_API_KEY environment variable or pass it in configuration."
            )

        verbose_proxy_logger.debug(
            "Initialized OpenAI Moderation Guardrail: %s with model: %s", guardrail_name, self.model
        )

    def _get_api_key(self) -> str | None:
        """Get API key from environment variables or litellm configuration"""
        import os

        import litellm
        from litellm.secret_managers.main import get_secret_str

        return (
            os.environ.get("OPENAI_API_KEY")
            or litellm.api_key
            or litellm.openai_key

View on GitHub (pinned to 77b7c6c40c)

Solutions

Set OPENAI_API_KEY in the proxy's runtime environment (compose env / k8s secret / .env per your deployment)
Or pass api_key explicitly under the guardrail's litellm_params in config.yaml
Verify the key is valid for the moderations API and the account has quota, then restart the proxy

Example fix

# before
guardrails:
  - guardrail_name: oai-moderation
    litellm_params:
      guardrail: openai_moderation
      mode: pre_call

# after (either)
guardrails:
  - guardrail_name: oai-moderation
    litellm_params:
      guardrail: openai_moderation
      mode: pre_call
      api_key: os.environ/OPENAI_API_KEY
# or export OPENAI_API_KEY=sk-... for the proxy process

Defensive patterns

Strategy: validation

Validate before calling

import os

if not (os.getenv("OPENAI_API_KEY") or cfg_guardrail_api_key):
    raise SystemExit(
        "openai_moderation guardrail configured but no api_key/OPENAI_API_KEY present"
    )

Try / catch

try:
    guard = OpenAIModerationGuardrail(guardrail_name="mod", **lp)
except ValueError as e:
    if "OPENAI_API_KEY" in str(e):
        secrets.load("openai"); guard = OpenAIModerationGuardrail(guardrail_name="mod", **lp)  # retry once after secret mount
    else:
        raise

Prevention

List guardrail secrets alongside model provider secrets in deployment manifests so they can't drift
Add a startup canary that calls the moderations endpoint once with 'ping' to validate key + quota early

When it happens

Trigger: Configuring guardrail: openai_moderation without api_key in litellm_params while OPENAI_API_KEY is unset in the proxy environment; relying on a generic OPENAI_API_KEY that was only set in the dev shell, not in the deployment; env var set to empty string

Common situations: Self-hosted proxy containers missing the OpenAI secret; teams assuming the guardrail reuses a model deployment's key (it does not share it automatically); adding moderation endpoints after initial deployment without updating secret stores

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/646728764f07b8b6. Report an issue: GitHub.