BerriAI/litellm · error · DeepKeepGuardrailMissingSecrets

DeepKeep API key is required. Set the `DEEPKEEP_API_KEY` env

Error message

DeepKeep API key is required. Set the `DEEPKEEP_API_KEY` environment variable or pass `api_key` in the guardrail config.

What it means

DeepKeepGuardrailMissingSecrets raised by DeepKeepGuardrail.__init__ when the DeepKeep guardrail is instantiated without an API key: neither the api_key constructor argument (from litellm_params) nor the DEEPKEEP_API_KEY environment variable is set. LiteLLM fails fast at guardrail registration because the DeepKeep firewall API cannot be called unauthenticated.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/deepkeep/deepkeep.py:80

              api_base: https://your-deepkeep-instance.example.com
              deepkeep_firewall_id: your-firewall-id
    """

    def __init__(
        self,
        api_key: str | None = None,
        api_base: str | None = None,
        firewall_id: str | None = None,
        unreachable_fallback: Literal["fail_closed", "fail_open"] = "fail_closed",
        extra_headers: Mapping[str, str] | list[str] | None = None,
        **kwargs: Any,
    ):
        self.async_handler = get_async_httpx_client(llm_provider=httpxSpecialProvider.GuardrailCallback)

        # API key
        deepkeep_api_key: Final = api_key or os.environ.get("DEEPKEEP_API_KEY")
        if not deepkeep_api_key:
            raise DeepKeepGuardrailMissingSecrets(
                "DeepKeep API key is required. Set the `DEEPKEEP_API_KEY` environment "
                "variable or pass `api_key` in the guardrail config."
            )
        self.deepkeep_api_key: str = deepkeep_api_key

        # Firewall ID
        self.firewall_id = firewall_id or os.environ.get("DEEPKEEP_FIREWALL_ID")
        if not self.firewall_id:
            raise DeepKeepGuardrailMissingSecrets(
                "DeepKeep firewall_id is required. Set the `DEEPKEEP_FIREWALL_ID` environment "
                "variable or pass `deepkeep_firewall_id` in the guardrail config."
            )

        # API base URL
        base_url = api_base or os.environ.get("DEEPKEEP_API_BASE")
        if not base_url:
            raise DeepKeepGuardrailMissingSecrets(
                "DeepKeep API base URL is required. Set the `DEEPKEEP_API_BASE` environment "

View on GitHub (pinned to 77b7c6c40c)

Solutions

Set DEEPKEEP_API_KEY in the environment the proxy actually runs in (docker -e, k8s secret, systemd Environment=) and restart
Or pass api_key: os.environ/DEEPKEEP_API_KEY under litellm_params in the guardrails entry
Verify with printenv DEEPKEEP_API_KEY inside the same service context
Check for typos and empty-string overrides of the variable name

Example fix

# before
guardrails:
  - guardrail_id: deepkeep
    litellm_params:
      mode: guardrail_runs_before_llm_call
      deepkeep_firewall_id: os.environ/DEEPKEEP_FIREWALL_ID

# after
# export DEEPKEEP_API_KEY=your-key
guardrails:
  - guardrail_id: deepkeep
    litellm_params:
      mode: guardrail_runs_before_llm_call
      api_key: os.environ/DEEPKEEP_API_KEY
      deepkeep_firewall_id: os.environ/DEEPKEEP_FIREWALL_ID

Defensive patterns

Strategy: validation

Validate before calling

import os

required = ('DEEPKEEP_API_KEY', 'DEEPKEEP_FIREWALL_ID', 'DEEPKEEP_API_BASE')
missing = [v for v in required if not os.environ.get(v)]
if missing:
    raise RuntimeError(f'DeepKeep guardrail disabled - unset env vars: {missing}')

Try / catch

from litellm.proxy.guardrails.guardrail_hooks.deepkeep.deepkeep import DeepKeepGuardrailMissingSecrets
try:
    guardrail = DeepKeepGuardrail(guardrail_name='deepkeep')
except DeepKeepGuardrailMissingSecrets as e:
    raise SystemExit(f'guardrail config incomplete: {e}') from e

Prevention

Store all three DeepKeep values (key, firewall id, base URL) as one secret-store entry so they cannot skew
Assert non-empty values in the deploy preflight - empty strings fail the same check
After rotation in the DeepKeep console, update the secret and restart the proxy in the same change

When it happens

Trigger: Adding a deepkeep guardrails entry in config.yaml with a mode hook (e.g. guardrail_runs_before_llm_call) but no api_key in litellm_params, while DEEPKEEP_API_KEY is unset in the proxy process environment.

Common situations: Key present in the developer shell but absent in the container/service; typo in the env var name; .env file not loaded by the deployment; key rotated in the console but never updated in the secret store.

Related errors

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