BerriAI/litellm · error · ValueError

prompt_id is required for Arize Phoenix prompt manager

Error message

prompt_id is required for Arize Phoenix prompt manager

What it means

The synchronous Arize Phoenix compile helper (_compile_prompt_helper) requires a prompt_id because Phoenix identifies prompts solely by ID. It raises ValueError immediately when prompt_id is None, before any Phoenix API call is attempted. This is a caller-side contract violation: the routing layer was unable to extract a prompt_id from the request.

Source

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

        self,
        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 an Arize Phoenix prompt template into a PromptManagementClient structure.

        This method:
        1. Loads the prompt version from Arize Phoenix
        2. Renders it with the provided variables
        3. Returns formatted chat messages
        4. Extracts model and optional parameters from metadata
        """
        if prompt_id is None:
            raise ValueError("prompt_id is required for Arize Phoenix prompt manager")
        try:
            # Load the prompt from Arize Phoenix if not already loaded
            if prompt_id not in self.prompt_manager.prompts:
                self.prompt_manager._load_prompt_from_arize(prompt_id)

            # Get the rendered messages and metadata
            rendered_messages, prompt_metadata = self.get_prompt_template(prompt_id, prompt_variables)

            # Extract model from metadata (if specified)
            template_model: Final = prompt_metadata.get("model")

            # Extract optional parameters from metadata
            optional_params: Final = {}
            for param in [
                "temperature",
                "max_tokens",
                "top_p",
                "frequency_penalty",

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set the prompt_id: use model='phoenix/<prompt_id>' or add prompt_id to litellm_params / the proxy model settings
Validate the model string format before routing (non-empty ID after 'phoenix/')
If you meant to use a prompt spec instead of an ID, that flow is not supported by the Phoenix manager — switch to a supported integration or supply the ID

Example fix

# before
params = {"model": "phoenix/"}  # empty prompt_id -> ValueError

# after
params = {"model": "phoenix/summarize-v2"}  # or params["prompt_id"] = "summarize-v2"

Defensive patterns

Strategy: validation

Validate before calling

def resolve_phoenix_model(prompt_id: str | None) -> str:
    if not prompt_id or not prompt_id.strip():
        raise ValueError("prompt_id must be a non-empty string")
    return f"phoenix/{prompt_id}"

model = resolve_phoenix_model(os.getenv("PHOENIX_PROMPT_ID"))

Type guard

def has_prompt_id(params: dict) -> bool:
    pid = params.get("prompt_id") or (params.get("model", "").split("/", 1)[1] if params.get("model", "").startswith("phoenix/") else None)
    return isinstance(pid, str) and len(pid.strip()) > 0

Try / catch

try:
    litellm.completion(model=f"phoenix/{prompt_id}", messages=[...])
except ValueError as e:
    if "prompt_id is required" in str(e):
        raise ValueError("Configure PHOENIX_PROMPT_ID before calling Phoenix-backed models") from e
    raise

Prevention

Assert a non-empty prompt ID at config load time
Fail fast on unset env vars that feed model strings (os.environ[...] not os.getenv(..., ''))
Add a unit test that every phoenix/* model in your config has a non-empty ID segment

When it happens

Trigger: Invoking the Phoenix prompt integration without a prompt_id, e.g. model='phoenix/' with an empty ID segment, or litellm_params that omit prompt_id while bitbucket/prompt spec fields are absent; a prompt_spec supplied instead of prompt_id (Phoenix does not support spec-based lookup); programmatic calls to _compile_prompt_helper(prompt_id=None, ...).

Common situations: Malformed model string 'phoenix/' (trailing slash with no ID); copy-pasting a config from another prompt integration that passes a spec instead of an ID; forgetting to set prompt_id in the proxy's model config for a Phoenix-based deployment.

Related errors

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