BerriAI/litellm · error · ValueError

prompt_id is required for Prompt Management Base class

Error message

prompt_id is required for Prompt Management Base class

What it means

The prompt-management base requires an explicit prompt id: the wrapper that injects managed prompts into a completion raises ValueError('prompt_id is required for Prompt Management Base class') when prompt_id is None. It fires when a prompt-management integration callback is active for a call that did not specify prompt_id — the callback cannot know which prompt to compile.

Solutions

Pass prompt_id (and prompt_variables) on every call that should use managed prompts
Scope the prompt integration to per-request callbacks instead of global registration so only intended calls are intercepted
Or drop the prompt-management callback if it was enabled accidentally

Example fix

# before
litellm.callbacks = ['langfuse']  # prompt integration registered globally
resp = litellm.completion(model='gpt-4o', messages=msgs)  # ValueError: prompt_id is required

# after
# only attach the prompt integration to calls that use it:
resp = litellm.completion(model='gpt-4o', messages=msgs)  # no global prompt callback
resp2 = litellm.completion(model='gpt-4o', messages=msgs, prompt_id='my-prompt', prompt_variables={'q': 'hi'})

Defensive patterns

Strategy: validation

Validate before calling

if prompt_integration_active(litellm.callbacks) and prompt_id is None:
    raise ValueError('prompt_id is required when a prompt-management integration is registered')
resp = litellm.completion(model=model, messages=messages)

Try / catch

try:
    resp = litellm.completion(model=model, messages=messages)
except ValueError as e:
    if 'prompt_id is required' in str(e):
        logger.error('prompt integration registered but call lacks prompt_id')
    raise

Prevention

Attach prompt-management integrations per request instead of globally when only some calls use prompts
Assert prompt_id/prompt_variables presence in your wrapper before calling litellm
Document which routes expect managed prompts so config and call sites stay in sync

When it happens

Trigger: Registering a prompt integration globally (litellm.callbacks, proxy litellm_settings callbacks) so every completion routes through prompt management, then issuing a plain litellm.completion(...)/acompletion(...) without prompt_id; mixed traffic where only some calls use managed prompts.

Common situations: Adding 'humanlike'/'langfuse'/prompt-layer style callback for one feature and breaking every other call in the service; proxy-wide callback config vs per-request prompt usage.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at litellm/integrations/prompt_management_base.py:168

        return model, completed_messages, updated_non_default_params

    def get_chat_completion_prompt(
        self,
        model: str,
        messages: list[AllMessageValues],
        non_default_params: dict,
        prompt_id: str | None,
        prompt_variables: dict | None,
        dynamic_callback_params: StandardCallbackDynamicParams,
        prompt_spec: PromptSpec | None = None,
        prompt_label: str | None = None,
        prompt_version: int | None = None,
        ignore_prompt_manager_model: bool | None = False,
        ignore_prompt_manager_optional_params: bool | None = False,
    ) -> tuple[str, list[AllMessageValues], dict]:
        if prompt_id is None:
            raise ValueError("prompt_id is required for Prompt Management Base class")
        if not self.should_run_prompt_management(
            prompt_id=prompt_id,
            prompt_spec=prompt_spec,
            dynamic_callback_params=dynamic_callback_params,
        ):
            return model, messages, non_default_params

        prompt_template: Final = self.compile_prompt(
            prompt_id=prompt_id,
            prompt_variables=prompt_variables,
            client_messages=messages,
            dynamic_callback_params=dynamic_callback_params,
            prompt_label=prompt_label,
            prompt_version=prompt_version,
        )

        return self.post_compile_prompt_processing(
            prompt_template=prompt_template,

View on GitHub (pinned to 77b7c6c40c)