BerriAI/litellm · error · ValueError

prompt_id is required when prompt_file is provided

Error message

prompt_id is required when prompt_file is provided

What it means

PromptManager.__init__ raises ValueError when prompt_file is given without prompt_id. Unlike prompt_directory (which derives ids from file stems) or prompt_data (keyed dicts), a single prompt file has no intrinsic id in this API, so the manager refuses to guess what key should map to self.prompts[prompt_id].

Solutions

  1. Pass prompt_id alongside prompt_file: PromptManager(prompt_file=..., prompt_id='greeting')
  2. Or switch to prompt_directory, which auto-registers every *.prompt file under its filename stem
  3. Or supply prompt_data dicts keyed by the desired ids instead of a file
  4. If config-driven, validate the config schema before constructing PromptManager

Example fix

# before
manager = PromptManager(prompt_file='prompts/greeting.prompt')

# after
manager = PromptManager(prompt_file='prompts/greeting.prompt', prompt_id='greeting')
Defensive patterns

Strategy: validation

Validate before calling

if prompt_file and not prompt_id:
    raise ValueError(f'prompt_id required when loading prompt_file={prompt_file}')
manager = PromptManager(prompt_id=prompt_id, prompt_file=prompt_file)

Try / catch

try:
    manager = PromptManager(prompt_file=path, prompt_id=prompt_id)
except ValueError as e:
    if 'prompt_id is required when prompt_file' in str(e):
        prompt_id = Path(path).stem  # derive an id and retry
        manager = PromptManager(prompt_file=path, prompt_id=prompt_id)
    else:
        raise

Prevention

When it happens

Trigger: PromptManager(prompt_file='prompts/greeting.prompt') with no prompt_id argument. Building the manager from a config dict where the id key is misspelled or dropped. Passing Path objects for prompt_file but forgetting the id is a separate positional/keyword arg.

Common situations: Switching from prompt_directory to a single-file setup and not realizing the id contract changes; YAML/env-driven config where prompt_id is optional and silently None; CI using a fixture prompt file without the id.

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

Appendix: source

Thrown at litellm/integrations/dotprompt/prompt_manager.py:84

        self.jinja_env = ImmutableSandboxedEnvironment(
            loader=DictLoader({}),
            autoescape=select_autoescape(["html", "xml"]),
            # Use Handlebars-style delimiters to match Dotprompt spec
            variable_start_string="{{",
            variable_end_string="}}",
            block_start_string="{%",
            block_end_string="%}",
            comment_start_string="{#",
            comment_end_string="#}",
        )

        # Load prompts from directory if provided
        if self.prompt_directory:
            self._load_prompts()

        if self.prompt_file:
            if not prompt_id:
                raise ValueError("prompt_id is required when prompt_file is provided")

            template: Final = self._load_prompt_file(self.prompt_file, prompt_id)
            self.prompts[prompt_id] = template

        # Load prompts from JSON data if provided
        if prompt_data:
            self._load_prompts_from_json(prompt_data, prompt_id)

    def _load_prompts(self) -> None:
        """Load all .prompt files from the prompt directory."""
        if not self.prompt_directory or not self.prompt_directory.exists():
            raise ValueError(f"Prompt directory does not exist: {self.prompt_directory}")

        prompt_files: Final = list(self.prompt_directory.glob("*.prompt"))

        for prompt_file in prompt_files:
            try:
                prompt_id = prompt_file.stem  # filename without extension

View on GitHub (pinned to 77b7c6c40c)