BerriAI/litellm · error · ValueError

Cannot set prompt_directory when working with…

Error message

Cannot set prompt_directory when working with prompt_initializer. Needs to be a specific dotprompt file

What it means

prompt_initializer (litellm/integrations/dotprompt/__init__.py) resolves exactly one prompt source: prompt_file, prompt_data, or dotprompt_content (DB-fetched), identified by prompt_id. If litellm_params also carries prompt_directory — the directory-mode setting used by the dotprompt manager — it raises this ValueError to remove ambiguity about which source should win.

Solutions

Remove prompt_directory from litellm_params when invoking a specific prompt file/data/ID
Or keep prompt_directory and drop prompt_file/dotprompt_content, letting the dotprompt manager resolve prompts from the directory by ID
Centralize the two configurations separately so they are never merged

Example fix

# before
litellm.completion(
    model="gpt-4",
    prompt_file="greeting.prompt",
    prompt_directory="/prompts",   # ValueError: ambiguous source
)

# after
litellm.completion(
    model="gpt-4",
    prompt_file="greeting.prompt",
)

Defensive patterns

Strategy: validation

Validate before calling

def prompt_params_unambiguous(litellm_params) -> None:
    has_specific = any(
        getattr(litellm_params, f, None)
        for f in ("prompt_file", "prompt_data", "dotprompt_content")
    )
    has_directory = bool(getattr(litellm_params, "prompt_directory", None))
    if has_specific and has_directory:
        raise ValueError("pass either prompt_directory OR a specific prompt source, not both")

Type guard

from typing import Any

def is_single_prompt_request(litellm_params: Any) -> bool:
    """True when params address one specific prompt and must not carry a directory."""
    return bool(getattr(litellm_params, "prompt_id", None) or getattr(litellm_params, "prompt_file", None))

Prevention

Keep two config presets: directory-mode and per-file-mode; never merge them
Strip prompt_directory in the code path that resolves a specific prompt file
Assert the exclusive-fields invariant in a config unit test

When it happens

Trigger: Copy-pasting directory-mode config (prompt_directory="/prompts") into a request that also specifies prompt_file="greeting.prompt" or prompt_id with dotprompt_content; reusing one PromptLiteLLMParams object across both usage styles.

Common situations: Migrating a project from directory-based dotprompt usage to per-file prompts and leaving the old field in shared config; templated litellm_params that defaults prompt_directory for every call.

Related errors

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

Appendix: source

Thrown at litellm/integrations/dotprompt/__init__.py:54

    from .prompt_manager import PromptManager

    # Parse the dotprompt content to extract frontmatter and content
    temp_manager: Final = PromptManager()
    metadata, content = temp_manager._parse_frontmatter(dotprompt_content)

    # Convert to prompt_data format
    return {"content": content.strip(), "metadata": metadata}


def prompt_initializer(litellm_params: "PromptLiteLLMParams", prompt_spec: "PromptSpec") -> "CustomPromptManagement":
    """
    Initialize a prompt from a .prompt file.
    """
    prompt_directory: Final = getattr(litellm_params, "prompt_directory", None)
    prompt_data = getattr(litellm_params, "prompt_data", None)
    prompt_id: Final = getattr(litellm_params, "prompt_id", None)
    if prompt_directory:
        raise ValueError(
            "Cannot set prompt_directory when working with prompt_initializer. Needs to be a specific dotprompt file"
        )

    prompt_file: Final = getattr(litellm_params, "prompt_file", None)

    # Handle dotprompt_content from database
    dotprompt_content: Final = getattr(litellm_params, "dotprompt_content", None)
    if dotprompt_content and not prompt_data and not prompt_file:
        prompt_data = _get_prompt_data_from_dotprompt_content(dotprompt_content)

    try:
        dot_prompt_manager: Final = DotpromptManager(
            prompt_directory=prompt_directory,
            prompt_data=prompt_data,
            prompt_file=prompt_file,
            prompt_id=prompt_id,
        )

View on GitHub (pinned to 77b7c6c40c)