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 compile() method of the Arize Phoenix prompt manager turns a stored Phoenix prompt into chat messages plus model parameters. It takes prompt_id as its identifier; because there is no default or ambient prompt context, prompt_id=None fails fast with this ValueError before any Phoenix call is made. The upstream prompt_initializer in litellm/integrations/arize/__init__.py reads prompt_id from litellm_params, so None usually means it was omitted there.

Solutions

Add `prompt_id: <your-phoenix-prompt-id>` to the model's litellm_params in your config
Check for the exact field name `prompt_id` (snake_case) — other spellings are ignored
Confirm the ID contains no path characters, since it will pass through _sanitize_id next

Example fix

# before
litellm_params:
  model: openai/gpt-4o
  api_base: https://app.phoenix.arize.com/s/workspace/v1
  api_key: os.environ/PHOENIX_API_KEY
  # prompt_id missing -> ValueError on compile

# after
litellm_params:
  model: openai/gpt-4o
  api_base: https://app.phoenix.arize.com/s/workspace/v1
  api_key: os.environ/PHOENIX_API_KEY
  prompt_id: UHJvbXB0OjE

Defensive patterns

Strategy: validation

Validate before calling

litellm_params = {
    "model": "openai/gpt-4o",
    "api_key": os.environ["PHOENIX_API_KEY"],
    "api_base": "http://localhost:6006",
}
if not litellm_params.get("prompt_id"):
    raise SystemExit("prompt_id is required for Arize Phoenix prompt models")

Type guard

def has_prompt_id(params: dict) -> bool:
    return isinstance(params.get("prompt_id"), str) and bool(params["prompt_id"].strip())

Try / catch

try:
    manager.compile(prompt_id=params.get("prompt_id"), prompt_variables=vars)
except ValueError as e:
    if "prompt_id is required" in str(e):
        raise SystemExit("Add prompt_id (the Phoenix prompt/version ID) to this model's litellm_params") from e
    raise

Prevention

Schema-validate prompt model entries: model + prompt_id + api_key + api_base are all mandatory
Use the exact snake_case field name prompt_id — variants are silently ignored and left as None

When it happens

Trigger: Routing a request to the Arize Phoenix prompt integration without `prompt_id` in the model's litellm_params, or calling manager.compile(None, ...) directly. Raised immediately, before the load/render steps.

Common situations: Configuring the model for Phoenix prompts but forgetting the prompt_id field (only api_key/api_base set); renaming the field (e.g. promptId) so litellm_params.prompt_id stays None; assuming the prompt is chosen by model_name.

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/6fb665a8ac6ad04c. Report an issue: GitHub.

Appendix: 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 77b7c6c40c)