BerriAI/litellm · error · ValueError

Either prompt_directory or prompt_data must be set before…

Error message

Either prompt_directory or prompt_data must be set before using dotprompt manager. Set litellm.global_prompt_directory, initialize with prompt_directory parameter, or provide prompt_data.

What it means

The dotprompt integration's prompt_manager property lazily constructs a PromptManager on first use and requires one of prompt_directory, prompt_data, or prompt_file to be configured — globally (litellm.global_prompt_directory), at init, or per request. If none is set, it raises this ValueError the moment a dotprompt model is first used, not at startup.

Solutions

Set litellm.global_prompt_directory = '/abs/path/to/prompts' before the first dotprompt call
Or pass prompt_directory when constructing the DotpromptManager
Or supply prompt_data / prompt_file per request so no directory is needed

Example fix

# before
import litellm
litellm.completion(model="dotprompt/gpt-4", messages=[])  # ValueError: no source configured

# after
import litellm
litellm.global_prompt_directory = "./prompts"   # contains greeting.prompt
litellm.completion(model="dotprompt/gpt-4:generate", messages=[])

Defensive patterns

Strategy: validation

Validate before calling

import os
import litellm

def dotprompt_ready() -> bool:
    mgr = getattr(litellm, "global_prompt_directory", None)
    return bool(mgr and os.path.isdir(mgr))

# before the first call:
# assert dotprompt_ready(), "set litellm.global_prompt_directory before dotprompt models"

Type guard

from typing import Any

def has_prompt_source(manager: Any) -> bool:
    """Manager can resolve prompts only with one of these set."""
    return bool(getattr(manager, "prompt_directory", None) or getattr(manager, "prompt_data", None) or getattr(manager, "prompt_file", None))

Prevention

Set litellm.global_prompt_directory once at process start, before any dotprompt model call
Smoke-test one dotprompt completion at deploy time to force the lazy init early
Ship the prompts directory in the container image and reference it by absolute path

When it happens

Trigger: Calling a completion with model="dotprompt/gpt-4" (or any dotprompt-prefixed route) without ever setting litellm.global_prompt_directory, without prompt_directory at DotpromptManager init, and without per-request prompt_data/prompt_file.

Common situations: Enabling the dotprompt integration and assuming prompts load from a default ./prompts directory; config that sets the directory on a different manager instance than the one serving requests; ordering issues where the model call happens before the global is assigned.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

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

            self.prompt_data = json.loads(prompt_data)
        else:
            self.prompt_data = prompt_data or {}

        self._prompt_manager: PromptManager | None = None
        self.prompt_file = prompt_file
        self.prompt_id = prompt_id

    @property
    def integration_name(self) -> str:
        """Integration name used in model names like 'dotprompt/gpt-4'."""
        return "dotprompt"

    @property
    def prompt_manager(self) -> PromptManager:
        """Lazy-load the prompt manager."""
        if self._prompt_manager is None:
            if self.prompt_directory is None and not self.prompt_data and not self.prompt_file:
                raise ValueError(
                    "Either prompt_directory or prompt_data must be set before using dotprompt manager. "
                    "Set litellm.global_prompt_directory, initialize with prompt_directory parameter, or provide prompt_data."
                )
            self._prompt_manager = PromptManager(
                prompt_directory=self.prompt_directory,
                prompt_data=self.prompt_data,
                prompt_file=self.prompt_file,
                prompt_id=self.prompt_id,
            )
        return self._prompt_manager

    def should_run_prompt_management(
        self,
        prompt_id: str | None,
        prompt_spec: PromptSpec | None,
        dynamic_callback_params: StandardCallbackDynamicParams,
    ) -> bool:
        """

View on GitHub (pinned to 77b7c6c40c)