BerriAI/litellm · error · ImportError

Setting tag-based guardrails is only available in…

Error message

Setting tag-based guardrails is only available in litellm-enterprise. You must be a premium user to use this feature.

What it means

Tag-based guardrail activation — event_hook configured as a Mode object with tags/defaults — is implemented only in the closed-source litellm_enterprise package. When _should_run_hook (default_on path) hits a Mode and the litellm_enterprise.integrations.custom_guardrail import fails, it raises this ImportError stating the feature requires the premium package.

Solutions

Install litellm_enterprise and configure your premium key (LITELLM_LICENSE) if you have an enterprise agreement
Otherwise flatten the config: use plain event_hook values (pre_call, during_call, post_call) instead of tag-based Modes
Confirm whether you actually need tag scoping before paying — plain modes cover most setups

Example fix

# before
MyGuardrail(event_hook=Mode(default=[GuardrailEventHooks.pre_call], tags={'team': ['support']}))
# ImportError: tag-based guardrails are only available in litellm-enterprise

# after
MyGuardrail(event_hook=[GuardrailEventHooks.pre_call])

Defensive patterns

Strategy: validation

Validate before calling

def enterprise_available() -> bool:
    try:
        import litellm_enterprise  # noqa: F401
        return True
    except ImportError:
        return False

if isinstance(guardrail.event_hook, Mode) and not enterprise_available():
    raise ConfigError('tag-based guardrail Modes require litellm-enterprise; use plain event_hook values')

Type guard

def is_mode_config(event_hook) -> bool:
    from litellm.types.utils import Mode
    return isinstance(event_hook, Mode)

Try / catch

except ImportError as e:
    if 'litellm-enterprise' in str(e):
        either install/license litellm_enterprise or replace Mode config with plain event_hook lists
    raise

Prevention

Keep enterprise-only config out of community deployments via config linting
Detect Mode objects in guardrail config at load time and reject them early on OSS
Document which YAML keys require the premium package

When it happens

Trigger: Configuring a guardrail with a Mode event_hook (mode containing tags: {...}) while litellm_enterprise is not installed or not licensed; default_on guardrails with tag-based modes on community litellm.

Common situations: Copying enterprise-style YAML examples into a community deployment; feature flags written for litellm-enterprise trialing on OSS; premium license expired or key not configured so the package import path is unavailable.

Related errors

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

Appendix: source

Thrown at litellm/integrations/custom_guardrail.py:782

            self.event_hook,
            requested_guardrails,
            self.default_on,
        )
        if self.default_on is True and self.guardrail_name in opted_out_global_guardrails:
            return False

        if self.default_on is True and disable_global_guardrail is True:
            return False

        if self.default_on is True and disable_global_guardrail is not True:
            if self._event_hook_is_event_type(event_type):
                if isinstance(self.event_hook, Mode):
                    try:
                        from litellm_enterprise.integrations.custom_guardrail import (
                            EnterpriseCustomGuardrailHelper,
                        )
                    except ImportError:
                        raise ImportError(
                            "Setting tag-based guardrails is only available in litellm-enterprise. You must be a premium user to use this feature."
                        )
                    result = EnterpriseCustomGuardrailHelper._should_run_if_mode_by_tag(
                        data, self.event_hook, event_type
                    )
                    if result is not None:
                        return result
                return True
            return False

        if (
            self.event_hook
            and not self._guardrail_is_in_requested_guardrails(requested_guardrails)
            and event_type.value != "logging_only"
        ):
            return False

        if not self._event_hook_is_event_type(event_type):

View on GitHub (pinned to 77b7c6c40c)