fix(callbacks): forward callback_settings to callback initializers and guard consumers against non-dict values

[yuneng-berri]

Relevant issues

Brings two related callback_settings fixes from litellm_yj_june10 into staging: #29590 and #30153

Type

Bug Fix

Changes

Three commits, all about how callback_settings reaches callback initialization.

#29590 makes load_config() forward the loaded callback_settings block to initialize_callbacks_on_proxy as callback_specific_params. Before, the callbacks branch called the initializer without that argument, so it defaulted to {} and any callback that reads its init params from callback_specific_params initialized empty. The visible symptom was DatadogCostManagementLogger always being constructed with cost_tag_keys=[], so the opt-in FinOps allowlist configured under callback_settings.datadog_cost_management.cost_tag_keys never took effect.

That forwarding also activates other consumers of callback_specific_params that were previously dormant from this call site. A non-dict value under one of their keys would reach **-unpack or .get(...) and abort proxy startup with TypeError / AttributeError. #29590 guarded lakera_prompt_injection against this. #30153 completes the guard by adding the same isinstance(dict) check to the compression_interception and websearch_interception consumers, so a non-dict value such as callback_settings: {compression_interception: true} is ignored and the callback initializes with its defaults instead of crashing the proxy. The presidio and datadog_cost_management consumers already had that guard

The Greptile review caught that the forwarded root value itself was still unguarded: a blank callback_settings: key in YAML loads as None, and config.get("callback_settings", {}) returns that None because dict.get only falls back to the default when the key is absent. Forwarded verbatim, it made the first "<name>" in callback_specific_params membership test raise TypeError: argument of type 'NoneType' is not iterable and abort startup; same failure for any non-dict root such as callback_settings: true. The third commit normalizes a non-dict callback_specific_params to {} at the initialize_callbacks_on_proxy boundary, which covers both callsites (load_config and init_guardrails), with regression tests at the unit and load_config level that fail with the exact TypeError before the fix

Proof of Fix

#29590: with the forwarding in place, a key whose metadata.tags carry the allowlisted tags produces Datadog Cost Management entries with those tags present; without it cost_tag_keys stays [].

#30153: booting the proxy with litellm_settings.callbacks: ["compression_interception"] and callback_settings: {compression_interception: true} aborts at startup before the change with AttributeError: 'bool' object has no attribute 'get', and boots cleanly after; the same holds for websearch_interception. The documented path (litellm_settings.compression_interception_params) is unaffected

Non-dict root guard: config with a blank callback_settings: key

model_list:
  - model_name: claude-haiku-4.5
    litellm_params:
      model: anthropic/claude-haiku-4-5

callback_settings:

litellm_settings:
  callbacks: ["compression_interception"]

general_settings:
  master_key: sk-1234

Before the guard, startup aborts:

$ python litellm/proxy/proxy_cli.py --config /tmp/blank_callback_settings.yaml --port 4010
...
  File ".../litellm/integrations/compression_interception/handler.py", line 75, in initialize_from_proxy_config
    elif "compression_interception" in callback_specific_params and isinstance(
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: argument of type 'NoneType' is not iterable

ERROR:    Application startup failed. Exiting.

After, the proxy boots and serves a real completion:

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:4010 (Press CTRL+C to quit)

$ curl -s http://localhost:4010/v1/chat/completions \
    -H "Authorization: Bearer sk-1234" \
    -H "Content-Type: application/json" \
    -d '{"model": "claude-haiku-4.5", "messages": [{"role": "user", "content": "Reply with exactly: callback_settings fix verified"}]}'
{
    "id": "chatcmpl-3bce5b65-feca-4122-b2f9-b1042cbd92d1",
    "model": "claude-haiku-4.5",
    "object": "chat.completion",
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "callback_settings fix verified",
                "role": "assistant"
            }
        }
    ],
    ...
}

[greptile-apps]

Greptile Summary

This PR fixes two related bugs in how callback_settings from the proxy YAML config reaches callback initializers. Previously, the callbacks branch in load_config omitted the callback_specific_params argument, so callbacks like DatadogCostManagementLogger always initialized with empty params. It also guards all affected consumers (compression_interception, websearch_interception, lakera_prompt_injection) against non-dict values at both the leaf and root level.

• proxy_server.py: forwards the loaded callback_settings block as callback_specific_params to initialize_callbacks_on_proxy, so configured allowlists (e.g. cost_tag_keys) now take effect.
• callback_utils.py: normalizes a non-dict callback_specific_params root (e.g. None from a blank callback_settings: key, or True) to {} at the function boundary, preventing TypeError on membership tests across all call sites.
• compression_interception/handler.py and websearch_interception/handler.py: add isinstance(..., dict) guards before consuming leaf values, preventing AttributeError when the value is a scalar like True.

Confidence Score: 5/5

The changes are narrowly scoped defensive guards and a single call-site argument addition; they cannot regress existing behavior and all new code paths are covered by regression tests.

Every changed code path adds a guard that either normalizes a value to a safe default or preserves an existing crash-free path. No logic that was previously working is altered, and the forwarding of callback_specific_params only activates dormant (now guarded) branches. The new tests directly reproduce the failure modes described in the PR.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/common_utils/callback_utils.py	Adds Optional[dict] signature and a non-dict normalization guard at the top of initialize_callbacks_on_proxy; also adds an isinstance(dict) check for lakera_prompt_injection to match the existing guards on other branches.
litellm/proxy/proxy_server.py	Forwards the loaded callback_settings block as callback_specific_params to initialize_callbacks_on_proxy; previously the argument was omitted and defaulted to {}.
litellm/integrations/compression_interception/handler.py	Adds isinstance(..., dict) guard before reading callback_specific_params["compression_interception"], preventing AttributeError when the value is a non-dict (e.g. True).
litellm/integrations/websearch_interception/handler.py	Same isinstance(..., dict) guard added for websearch_interception, mirroring the compression handler fix.
tests/test_litellm/proxy/common_utils/test_callback_utils.py	New regression tests for non-dict lakera_prompt_injection values and for None/True as the callback_specific_params root; uses monkeypatching with no real network calls.
tests/test_litellm/proxy/proxy_server/test_proxy_config.py	Two new integration-level regression tests: one verifies callback_specific_params forwarding, the other verifies blank callback_settings: (YAML None) does not crash startup.
tests/test_litellm/integrations/compression_interception/test_compression_interception_handler.py	New unit tests for the non-dict and valid-dict paths in CompressionInterceptionLogger.initialize_from_proxy_config.
tests/test_litellm/integrations/websearch_interception/test_websearch_interception_handler.py	New unit tests for the non-dict and valid-dict paths in WebSearchInterceptionLogger.initialize_from_proxy_config.

_{Reviews (2): Last reviewed commit: "fix(callbacks): normalize non-dict callb..." | Re-trigger Greptile}

[greptile-apps]

Top-level callback_settings not guarded against non-dict values

callback_settings = config.get("callback_settings", {}) only falls back to {} when the key is absent. If the YAML contains callback_settings: (blank, resolving to None) or callback_settings: true, the raw non-dict value is forwarded here. Inside initialize_callbacks_on_proxy, every branch evaluates "key" in callback_specific_params before the leaf-level isinstance(..., dict) guard — "presidio" in None and "presidio" in True both raise TypeError, aborting proxy startup.

The PR fixes non-dict leaves (e.g. callback_settings.compression_interception: true) but misses the non-dict root case introduced by the forwarding. A minimal fix is to pass callback_specific_params=callback_settings if isinstance(callback_settings, dict) else {}.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[yuneng-berri]

@greptile