diff --git a/docs/my-website/docs/troubleshoot/max_callbacks.md b/docs/my-website/docs/troubleshoot/max_callbacks.md new file mode 100644 index 0000000000..4b0f3e24b7 --- /dev/null +++ b/docs/my-website/docs/troubleshoot/max_callbacks.md @@ -0,0 +1,68 @@ +# MAX_CALLBACKS Limit + +## Error Message + +``` +Cannot add callback - would exceed MAX_CALLBACKS limit of 30. Current callbacks: 30 +``` + +## What This Means + +LiteLLM limits the number of callbacks that can be registered to prevent performance degradation. Each callback runs on every LLM request, so having too many callbacks can cause exponential CPU usage and slow down your proxy. + +The default limit is **30 callbacks**. + +## When You Might Hit This Limit + +- **Large enterprise deployments** with many teams, each having their own guardrails +- **Multiple logging integrations** combined with custom callbacks +- **Per-team callback configurations** that add up across your organization + +## How to Override + +Set the `LITELLM_MAX_CALLBACKS` environment variable to increase the limit: + +```bash +# Docker +docker run -e LITELLM_MAX_CALLBACKS=100 ... + +# Docker Compose +environment: + - LITELLM_MAX_CALLBACKS=100 + +# Kubernetes +env: + - name: LITELLM_MAX_CALLBACKS + value: "100" + +# Direct +export LITELLM_MAX_CALLBACKS=100 +litellm --config config.yaml +``` + +## Recommendations + +1. **Start conservative** - Only increase as much as you need. If you have 60 teams with guardrails, try `LITELLM_MAX_CALLBACKS=75` to leave headroom. + +2. **Monitor performance** - More callbacks means more processing per request. Watch your CPU usage and response latency after increasing the limit. + +3. **Consolidate where possible** - If multiple teams use identical guardrails, consider using shared callback configurations rather than per-team duplicates. + +## Example: Large Enterprise Setup + +For an organization with 60+ teams, each with a guardrail callback: + +```yaml +# config.yaml +litellm_settings: + callbacks: ["prometheus", "langfuse"] # 2 global callbacks + +# Each team adds 1 guardrail callback = 60+ callbacks +# Total: 62+ callbacks needed +``` + +Set the environment variable: + +```bash +export LITELLM_MAX_CALLBACKS=100 +``` diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index 37392ff5c1..0d95bf7e54 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -1081,6 +1081,7 @@ const sidebars = { "troubleshoot/cpu_issues", "troubleshoot/memory_issues", "troubleshoot/spend_queue_warnings", + "troubleshoot/max_callbacks", ], }, ], diff --git a/litellm/constants.py b/litellm/constants.py index 3c618723d6..f5f2c7a49e 100644 --- a/litellm/constants.py +++ b/litellm/constants.py @@ -2,6 +2,8 @@ import os import sys from typing import List, Literal +from litellm.litellm_core_utils.env_utils import get_env_int + DEFAULT_HEALTH_CHECK_PROMPT = str( os.getenv("DEFAULT_HEALTH_CHECK_PROMPT", "test from litellm") ) @@ -99,6 +101,11 @@ DEFAULT_REASONING_EFFORT_MINIMAL_THINKING_BUDGET_GEMINI_2_5_FLASH_LITE = int( ) ) +# Maximum number of callbacks that can be registered +# This prevents callbacks from exponentially growing and consuming CPU resources +# Override with LITELLM_MAX_CALLBACKS env var for large deployments (e.g., many teams with guardrails) +MAX_CALLBACKS = get_env_int("LITELLM_MAX_CALLBACKS", 30) + # Generic fallback for unknown models DEFAULT_REASONING_EFFORT_MINIMAL_THINKING_BUDGET = int( os.getenv("DEFAULT_REASONING_EFFORT_MINIMAL_THINKING_BUDGET", 128) diff --git a/litellm/litellm_core_utils/env_utils.py b/litellm/litellm_core_utils/env_utils.py new file mode 100644 index 0000000000..34c6527533 --- /dev/null +++ b/litellm/litellm_core_utils/env_utils.py @@ -0,0 +1,21 @@ +""" +Utility helpers for reading and parsing environment variables. +""" + +import os + + +def get_env_int(env_var: str, default: int) -> int: + """Parse an environment variable as an integer, falling back to default on invalid values. + + Handles empty strings, whitespace, and non-numeric values gracefully + so that misconfiguration doesn't crash the process at import time. + """ + raw = os.getenv(env_var) + if raw is None: + return default + raw = raw.strip() + try: + return int(raw) + except (ValueError, TypeError): + return default diff --git a/litellm/litellm_core_utils/logging_callback_manager.py b/litellm/litellm_core_utils/logging_callback_manager.py index 435ae078a6..34d2581737 100644 --- a/litellm/litellm_core_utils/logging_callback_manager.py +++ b/litellm/litellm_core_utils/logging_callback_manager.py @@ -2,6 +2,7 @@ from typing import TYPE_CHECKING, Callable, Dict, List, Optional, Set, Type, Uni import litellm from litellm._logging import verbose_logger +from litellm.constants import MAX_CALLBACKS from litellm.integrations.additional_logging_utils import AdditionalLoggingUtils from litellm.integrations.custom_logger import CustomLogger from litellm.integrations.generic_api.generic_api_callback import GenericAPILogger @@ -24,9 +25,6 @@ class LoggingCallbackManager: - Keep a reasonable MAX_CALLBACKS limit (this ensures callbacks don't exponentially grow and consume CPU Resources) """ - # healthy maximum number of callbacks - unlikely someone needs more than 20 - MAX_CALLBACKS = 30 - def add_litellm_input_callback(self, callback: Union[CustomLogger, str]): """ Add a input callback to litellm.input_callback @@ -155,9 +153,9 @@ class LoggingCallbackManager: Check if adding another callback would exceed MAX_CALLBACKS Returns True if safe to add, False if would exceed limit """ - if len(parent_list) >= self.MAX_CALLBACKS: + if len(parent_list) >= MAX_CALLBACKS: verbose_logger.warning( - f"Cannot add callback - would exceed MAX_CALLBACKS limit of {self.MAX_CALLBACKS}. Current callbacks: {len(parent_list)}" + f"Cannot add callback - would exceed MAX_CALLBACKS limit of {MAX_CALLBACKS}. Current callbacks: {len(parent_list)}" ) return False return True