BerriAI/litellm · warning · ValueError

Each entry in `fallback_sap_modules` must include a 'model'

Error message

Each entry in `fallback_sap_modules` must include a 'model' key.

What it means

When building the SAP module chain, each entry in the fallback_sap_modules list must name the fallback model via a 'model' key; LiteLLM pops 'model' (and 'messages') from each dict to build a fallback prompt module. If 'model' is absent or None, this ValueError is raised before the request is sent.

Source

Thrown at litellm/llms/sap/chat/transformation.py:348

                stream_config["chunk_size"] = stream_options["chunk_size"]
            if "delimiters" in stream_options:
                stream_config["delimiters"] = stream_options["delimiters"]

        optional_params.pop("tool_choice", None)

        modules: Final = [
            self._build_prompt_module(
                model_name=model,
                template_messages=template,
                params=dict(optional_params),
            )
        ]

        for modules_dict in fallback_modules:
            modules_dict = dict(modules_dict)
            fallback_model = modules_dict.pop("model", None)
            if fallback_model is None:
                raise ValueError("Each entry in `fallback_sap_modules` must include a 'model' key.")
            fallback_model = fallback_model.removeprefix("sap/")
            fallback_template = modules_dict.pop("messages", [])

            modules.append(
                self._build_prompt_module(
                    model_name=fallback_model,
                    template_messages=fallback_template,
                    params=modules_dict,
                )
            )

        config_payload: Final[dict[str, Any]] = {
            "modules": modules if len(modules) > 1 else modules[0],
        }
        if stream_config:
            config_payload["stream"] = stream_config

        request_body: Final[dict[str, Any]] = {"config": config_payload}

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Add 'model' to every fallback entry: fallback_sap_modules=[{'model': 'sap/gpt-4o', 'messages': [...]}].
2. If the model string includes the 'sap/' prefix it is stripped automatically, but the key itself must be named exactly 'model'.
3. Validate the list shape at startup: assert all('model' in entry for entry in fallback_sap_modules).

Example fix

# before
fallback_sap_modules=[{'messages': [{'role': 'user', 'content': 'hi'}]}]
# after
fallback_sap_modules=[{'model': 'sap/gpt-4o', 'messages': [{'role': 'user', 'content': 'hi'}]}]

def validate_fallbacks(entries: list[dict]) -> list[dict]:
    for i, entry in enumerate(entries):
        if not entry.get('model'):
            raise ValueError(f'fallback_sap_modules[{i}] is missing required key "model"')
    return entries

When it happens

Trigger: Calling a sap/ model with fallback_sap_modules=[{'messages': [...]}] or any entry whose 'model' key is missing/None - e.g. only template messages or params were supplied for the fallback.

Common situations: Reusing fallback_configs written for OpenAI-style fallbacks (which use 'model' at a different nesting level); dynamically building fallback entries where the model key is conditionally set; typos like 'model_name' instead of 'model'.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• For SAP Masking Module Config you must provide 'providers'.
• For using SAP Filtering Module you must provide at least one
• TranslationModuleConfig requires at least one of 'input' or
• Content must be a string
• Cannot specify both maxChunkCount and maxDocumentCount.

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