BerriAI/litellm · error · ValueError

Error compiling prompt

Error message

Error compiling prompt '{prompt_id}': {e}

What it means

LiteLLM's Arize Phoenix prompt-management integration raises this ValueError as a catch-all: any exception thrown while loading the prompt from the Phoenix server (_load_prompt_from_arize) or rendering its template with your variables (get_prompt_template) is caught in _compile_prompt_helper and re-raised as "Error compiling prompt '<id>': <cause>". The text after the colon is the original exception and is the only clue to the real failure (connectivity, auth, unknown prompt id, or a template-variable error). It fires during a completion call with prompt management enabled, not at startup.

Solutions

  1. Read the suffix of the message after ': ' — it names the actual cause (connection error, KeyError on a variable, auth failure) and dictates the fix
  2. Verify the Phoenix connection env vars (PHOENIX_COLLECTOR_ENDPOINT / PHOENIX_API_KEY, or the ARIZE_PHOENIX_* pair your setup uses)
  3. Confirm the prompt_id exists server-side: call manager.get_available_prompts() or prompt_manager.list_templates() and compare
  4. Pass every variable the template references via prompt_variables on the litellm call
  5. If Phoenix was upgraded or the prompt migrated, re-save the prompt and confirm the id and version still resolve

Example fix

// before
response = litellm.completion(
    model="gpt-4o-mini",
    prompt_id="support-triage",  # template uses {{ticket_text}}
    messages=[],                 # no variables supplied -> render error wrapped in 280
)
// after
response = litellm.completion(
    model="gpt-4o-mini",
    prompt_id="support-triage",
    prompt_variables={"ticket_text": customer_ticket},
    messages=[],
)
Defensive patterns

Strategy: try-catch

Validate before calling

available = mgr.get_available_prompts()
if "support-triage" not in available:
    raise SystemExit(f"prompt_id not in Phoenix; available: {available}")
required_vars = {"ticket_text"}
if not required_vars.issubset(prompt_variables or {}):
    raise ValueError(f"missing template variables: {required_vars - set(prompt_variables or {})}")

Try / catch

try:
    resp = litellm.completion(model=model, prompt_id="support-triage",
                              prompt_variables=variables)
except ValueError as e:
    if "Error compiling prompt" in str(e):
        cause = str(e).split(": ", 1)[-1]  # original exception text
        logger.error("phoenix prompt compile failed: %s", cause)
        raise
    raise

Prevention

When it happens

Trigger: A completion/acompletion call with the arize_phoenix prompt integration active where: (1) the Phoenix endpoint (PHOENIX_COLLECTOR_ENDPOINT / PHOENIX_HOST) is unreachable or misconfigured; (2) prompt_id does not exist on the Phoenix server so _load_prompt_from_arize fails; (3) the template references variables absent from prompt_variables so rendering raises; (4) the Phoenix API key is missing or invalid; (5) prompt metadata returned by Phoenix has an unexpected shape.

Common situations: Wrong or missing PHOENIX_* env vars in the deployment; prompt renamed or deleted in the Phoenix UI leaving a stale prompt_id; passing prompt_variables={} or forgetting one required variable; Phoenix server upgrade changing the client API; self-hosted Phoenix instance blocked by firewall or mTLS.

Related errors

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

Appendix: source

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

                "temperature",
                "max_tokens",
                "top_p",
                "frequency_penalty",
                "presence_penalty",
            ]:
                if param in prompt_metadata:
                    optional_params[param] = prompt_metadata[param]

            return PromptManagementClient(
                prompt_id=prompt_id,
                prompt_template=rendered_messages,
                prompt_template_model=template_model,
                prompt_template_optional_params=optional_params,
                completed_messages=None,
            )

        except Exception as e:
            raise ValueError(f"Error compiling prompt '{prompt_id}': {e}")

    async def async_compile_prompt_helper(
        self,
        prompt_id: str | None,
        prompt_variables: dict | None,
        dynamic_callback_params: StandardCallbackDynamicParams,
        prompt_spec: PromptSpec | None = None,
        prompt_label: str | None = None,
        prompt_version: int | None = None,
    ) -> PromptManagementClient:
        """
        Async version of compile prompt helper. Since Arize Phoenix operations are synchronous,
        this simply delegates to the sync version.
        """
        if prompt_id is None:
            raise ValueError("prompt_id is required for Arize Phoenix prompt manager")
        return self._compile_prompt_helper(
            prompt_id=prompt_id,

View on GitHub (pinned to 77b7c6c40c)