What causes "prompt_id is required for dotprompt manager" in BerriAI/litellm?

Use the full model form: model="dotprompt/my_prompt" (optionally "dotprompt/my_prompt:variant")

BerriAI/litellm · error · ValueError

prompt_id is required for dotprompt manager

Error message

prompt_id is required for dotprompt manager

What it means

compile_prompt_helper in DotpromptManager requires a non-None prompt_id — the identifier that selects which .prompt file to load (normally extracted from the model string "dotprompt/<prompt_id>"). A None prompt_id raises this ValueError before any template lookup happens.

Solutions

Use the full model form: model="dotprompt/my_prompt" (optionally "dotprompt/my_prompt:variant")
Log the model string before the call and fix the code path that produces an empty prompt ID
If calling the helper directly, always pass a concrete prompt_id string

Example fix

# before
prompt_name = None  # lookup failed earlier
resp = litellm.completion(model=f"dotprompt/{prompt_name}", ...)  # 'dotprompt/None' or missing id

# after
prompt_name = "greeting"
assert prompt_name, "prompt id must resolve before calling"
resp = litellm.completion(model=f"dotprompt/{prompt_name}", ...)

Defensive patterns

Strategy: validation

Validate before calling

import re

DOTPROMPT_MODEL = re.compile(r"^dotprompt/([^:/]+)(?::([^/]+))?$")

def parse_dotprompt_model(model: str) -> tuple[str, str | None] | None:
    m = DOTPROMPT_MODEL.match(model or "")
    return (m.group(1), m.group(2)) if m else None

# before the call:
# parsed = parse_dotprompt_model(model)
# assert parsed and parsed[0], f"model must be dotprompt/<prompt_id>, got {model!r}"

Type guard

from typing import Any

def has_prompt_id(prompt_id: Any) -> bool:
    """compile_prompt_helper requires a concrete, non-empty id string."""
    return isinstance(prompt_id, str) and len(prompt_id) > 0

Prevention

Validate the dotprompt model string at request ingress (regex above)
Never build model names from unvalidated optional variables; default and assert them
Log model + prompt_id together so empty ids are obvious in traces

When it happens

Trigger: Model string of exactly "dotprompt/" or "dotprompt" with no ID after the slash; calling compile_prompt_helper(prompt_id=None, ...) directly; routing code that splits the model name and passes an empty/None component.

Common situations: Dynamically building the model string from a variable that is empty for some requests; typos in proxy model aliases; custom routers that strip the suffix.

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/fc8b2d317a627fec. Report an issue: GitHub.

Appendix: source

Thrown at litellm/integrations/dotprompt/dotprompt_manager.py:124

        prompt_id: str | None,
        prompt_spec: PromptSpec | None,
        prompt_variables: dict | None,
        dynamic_callback_params: StandardCallbackDynamicParams,
        prompt_label: str | None = None,
        prompt_version: int | None = None,
    ) -> PromptManagementClient:
        """
        Compile a .prompt file into a PromptManagementClient structure.

        This method:
        1. Loads the prompt template from the .prompt file (with optional version)
        2. Renders it with the provided variables
        3. Converts the rendered text into chat messages
        4. Extracts model and optional parameters from metadata
        """

        if prompt_id is None:
            raise ValueError("prompt_id is required for dotprompt manager")

        try:
            # Get the prompt template (versioned or base)
            template: Final = self.prompt_manager.get_prompt(prompt_id=prompt_id, version=prompt_version)
            if template is None:
                version_str: Final = f" (version {prompt_version})" if prompt_version else ""
                raise ValueError(f"Prompt '{prompt_id}'{version_str} not found in prompt directory")

            # Render the template with variables (pass version for proper lookup)
            rendered_content: Final = self.prompt_manager.render(
                prompt_id=prompt_id,
                prompt_variables=prompt_variables,
                version=prompt_version,
            )

            # Convert rendered content to chat messages
            messages: Final = self._convert_to_messages(rendered_content)

View on GitHub (pinned to 77b7c6c40c)