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

PromptManagementBase.add_prompt_management_to_request is the hook that expands a model alias like 'promptlayer/<prompt_id>' into full messages. If prompt_id resolves to None (no id in the model string, no prompt_spec, no default on the callback), it raises ValueError immediately — there is nothing to compile.

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 6c2dcb801b)

Solutions

Pass a concrete prompt id in the model string, e.g. litellm.completion(model="promptlayer/<your-prompt-id>", ...)
If using a custom PromptManagementBase subclass, set the default prompt id (e.g. self.prompt_id in __init__ or via dynamic_callback_params)
If the request should not use prompt management, route it to a plain model name without the integration prefix

Example fix

# before
response = litellm.completion(model="promptlayer/", messages=messages)
# ValueError: prompt_id is required for Prompt Management Base class

# after
response = litellm.completion(model="promptlayer/1729", messages=messages)

Defensive patterns

Strategy: validation

Validate before calling

import re

def prompt_id_from_model(model: str) -> str | None:
    m = re.match(r"^(promptlayer|anthropic_prompt|promptforge)/(.+)$", model)
    return m.group(2) if m and m.group(2) else None

assert prompt_id_from_model(requested_model), "model alias must include a prompt id"

Type guard

from typing import TypeGuard

def has_prompt_id(prompt_id: str | None) -> TypeGuard[str]:
    return isinstance(prompt_id, str) and prompt_id.strip() != ""

Try / catch

try:
    model, messages, params = pm.add_prompt_management_to_request(
        model, messages, non_default_params, prompt_id, prompt_variables, {}
    )
except ValueError as e:
    if "prompt_id is required" in str(e):
        raise ValueError(f"Model '{model}' needs a prompt id, e.g. promptlayer/<id>") from e
    raise

Prevention

Encode the prompt id in the model alias at config time and lint aliases for a non-empty id segment
Give custom PromptManagementBase subclasses a default prompt id if they are always bound to one prompt
Route non-prompt traffic to plain model names so the prompt-management hook never sees prompt_id=None

When it happens

Trigger: Routing a request to a prompt-management integration without an id: model='promptlayer/' (empty id), a callback subclass with no initial/default prompt id, or a code path that calls add_prompt_management_to_request(prompt_id=None) directly.

Common situations: Typos in the model alias; registering a custom prompt-management callback but forgetting to set its default prompt id; renaming prompts in the manager so the alias no longer parses.

Related errors

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