BerriAI/litellm · error · ValueError

Prompt template '{prompt_id}' not found

Error message

Prompt template '{prompt_id}' not found

What it means

Raised by litellm's Arize Phoenix prompt integration when get_prompt_template() cannot find a template for the given prompt_id. The manager first calls get_template(prompt_id) on the underlying Phoenix prompt manager, and if that returns None or an empty value the lookup is treated as a failure. This almost always means the prompt does not exist in your Arize Phoenix instance (or was deleted/renamed) rather than a transient error.

Source

Thrown at litellm/integrations/arize/arize_phoenix_prompt_manager.py:260

    def get_prompt_template(
        self,
        prompt_id: str,
        prompt_variables: dict[str, Any] | None = None,
    ) -> tuple[list[AllMessageValues], dict[str, Any]]:
        """
        Get a prompt template and render it with variables.

        Args:
            prompt_id: The ID of the prompt version
            prompt_variables: Variables to substitute in the template

        Returns:
            Tuple of (rendered_messages, metadata)
        """
        template: Final = self.prompt_manager.get_template(prompt_id)
        if not template:
            raise ValueError(f"Prompt template '{prompt_id}' not found")

        # Render the template
        rendered_messages: Final = self.prompt_manager.render_template(prompt_id, prompt_variables or {})

        # Extract metadata
        metadata: Final = {
            "model": template.model,
            "temperature": template.temperature,
            "max_tokens": template.max_tokens,
        }

        # Add additional invocation parameters
        invocation_params: Final = template.invocation_parameters
        provider_params = {}

        if "openai" in invocation_params:
            provider_params = invocation_params["openai"]
        elif "anthropic" in invocation_params:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Verify the prompt exists: open Arize Phoenix (Prompts tab) or call the Phoenix client (client.get_prompt(prompt_id)) and confirm the exact prompt_id spelling
2. Check the Phoenix connection settings (ARIZE_PHOENIX endpoint / API key env vars or however the integration was initialized) so that _load_prompt_from_arize can actually fetch prompts
3. If the prompt was renamed or versioned, update the model string / litellm_params to the current prompt_id
4. If prompts must be pre-loaded, call the prompt manager's load API at startup and fail loudly there instead of at request time

Example fix

# before
response = litellm.completion(model="phoenix/my-prompt", messages=[{"role": "user", "content": "hi"}])  # ValueError: Prompt template 'my-prompt' not found

# after
# confirm the prompt exists first
import phoenix as px
px.Client().get_prompt("my-prompt")  # raises early with a clearer error if missing
response = litellm.completion(model="phoenix/my-prompt", messages=[{"role": "user", "content": "hi"}])

from phoenix import Client

def prompt_exists(prompt_id: str) -> bool:
    try:
        px = Client()
        px.get_prompt(prompt_id)
        return True
    except Exception:
        return False

assert prompt_exists("summarize-v2"), "prompt missing in Phoenix"

def is_valid_prompt_id(prompt_id: str | None) -> bool:
    return isinstance(prompt_id, str) and bool(prompt_id.strip())

try:
    resp = litellm.completion(model=f"phoenix/{prompt_id}", messages=[...])
except ValueError as e:
    if "not found" in str(e):
        # unknown prompt: surface config error, do not retry
        raise ConfigError(f"Phoenix prompt {prompt_id} missing") from e
    raise

When it happens

Trigger: Calling completion with a prompt managed by Arize Phoenix (e.g. model='phoenix/<prompt_id>' or via prompt_id in litellm_params) where prompt_id has no corresponding prompt in Phoenix; the prompt failed to load from the Phoenix API earlier (network/auth failure silently left it out of prompt_manager.prompts); referencing a deleted prompt version.

Common situations: Typos in the prompt_id in the model string; prompt was deleted or renamed in the Phoenix UI after the integration was configured; Phoenix endpoint/API key misconfigured so the initial _load_prompt_from_arize never populated the cache; using a prompt_id from a different Phoenix project/workspace.

Related errors

• prompt_id is required for Arize Phoenix prompt manager
• Error compiling prompt '{prompt_id}': {e}
• bitbucket_config is required for BitBucket prompt integratio
• Error compiling prompt: {e}. Prompt id={prompt_id}
• prompt_id is required for Prompt Management Base class

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