fix(callbacks): allow MAX_CALLBACKS override via env var (#20781)

* fix(callbacks): allow MAX_CALLBACKS override via env var (#20778)

* fix(callbacks): allow MAX_CALLBACKS override via env var

- Move MAX_CALLBACKS from logging_callback_manager.py to constants.py
- Add LITELLM_MAX_CALLBACKS env var override (default: 30)
- Add troubleshooting doc explaining the limit and override

Fixes issue where large deployments with 60+ teams using guardrails
would hit the hardcoded MAX_CALLBACKS=30 limit and fail to start.

* docs: add max_callbacks to sidebar navigation

---------

Co-authored-by: shin-bot-litellm <shin-bot-litellm@users.noreply.github.com>

* fix callbacks issue

---------

Co-authored-by: shin-bot-litellm <shin-bot-litellm@berri.ai>
Co-authored-by: shin-bot-litellm <shin-bot-litellm@users.noreply.github.com>

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
+```

docs/my-website/sidebars.js

@@ -1081,6 +1081,7 @@ const sidebars = {
         "troubleshoot/cpu_issues",
         "troubleshoot/memory_issues",
         "troubleshoot/spend_queue_warnings",
+        "troubleshoot/max_callbacks",
       ],
     },
   ],

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)

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

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