BerriAI/litellm · error · DeepKeepGuardrailMissingSecrets

DeepKeep firewall_id is required. Set the `DEEPKEEP_FIREWALL

Error message

DeepKeep firewall_id is required. Set the `DEEPKEEP_FIREWALL_ID` environment variable or pass `deepkeep_firewall_id` in the guardrail config.

What it means

DeepKeepGuardrailMissingSecrets raised by DeepKeepGuardrail.__init__ when no firewall_id is available: neither the firewall_id constructor argument (configurable via litellm_params as deepkeep_firewall_id) nor the DEEPKEEP_FIREWALL_ID environment variable is set. DeepKeep scopes every guard call to a specific firewall instance, so the guardrail refuses to register without it.

Source

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

        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 "
                "variable or pass `api_base` in the guardrail config."
            )

        # Normalize the API base – ensure it ends with the guardrail endpoint
        base_url = base_url.rstrip("/")
        if base_url.endswith(_DEEPKEEP_GUARDRAIL_ENDPOINT.rstrip("/")):
            self.api_base = base_url
        else:
            self.api_base = f"{base_url}{_DEEPKEEP_GUARDRAIL_ENDPOINT}"

View on GitHub (pinned to 77b7c6c40c)

Solutions

Set DEEPKEEP_FIREWALL_ID in the proxy environment and restart
Or add deepkeep_firewall_id under litellm_params in the guardrails entry
Copy the firewall ID exactly from the DeepKeep console (no stray whitespace/quotes)
Confirm which key your litellm version reads from litellm_params (deepkeep_firewall_id) and match it

Example fix

# before
guardrails:
  - guardrail_id: deepkeep
    litellm_params:
      mode: guardrail_runs_before_llm_call
      api_key: os.environ/DEEPKEEP_API_KEY

# after
# export DEEPKEEP_FIREWALL_ID=your-firewall-id
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

fw = os.environ.get('DEEPKEEP_FIREWALL_ID')
if not fw or not fw.strip():
    raise RuntimeError('DEEPKEEP_FIREWALL_ID missing/empty - copy the firewall id from the DeepKeep console')

Try / catch

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

Prevention

Note the naming asymmetry: env var DEEPKEEP_FIREWALL_ID vs litellm_params key deepkeep_firewall_id - validate both spellings
Copy the firewall id verbatim from the DeepKeep console; strip whitespace when templating
Include the firewall id in the same preflight check as the API key

When it happens

Trigger: A deepkeep guardrails entry that supplies api_key/api_base but omits deepkeep_firewall_id in litellm_params while DEEPKEEP_FIREWALL_ID is unset; note the config key name (deepkeep_firewall_id) differs from the env var name (DEEPKEEP_FIREWALL_ID), a common trip point.

Common situations: Docs example copied with only the API key filled in; firewall ID known in the DeepKeep console but never added to the deployment; using the wrong litellm_params key name (firewall_id vs deepkeep_firewall_id).

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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