BerriAI/litellm · error · ValueError

prompt_id is required for Langfuse prompt management

Error message

prompt_id is required for Langfuse prompt management

What it means

The Langfuse prompt-management client requires a concrete prompt identifier: _compile_prompt_helper raises ValueError when prompt_id is None. LiteLLM passes prompt_id from the callback parameters or the PromptSpec; if you enable Langfuse prompt management but never name a prompt, there is nothing to fetch from Langfuse, so this fails fast.

Source

Thrown at litellm/integrations/langfuse/langfuse_prompt_management.py:243

            allow_env_credentials=dynamic_callback_params.get("langfuse_host") is None,
        )
        langfuse_prompt_client: Final = self._get_prompt_from_id(
            langfuse_prompt_id=prompt_id,
            langfuse_client=langfuse_client,
        )
        return langfuse_prompt_client is not None

    def _compile_prompt_helper(
        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:
        if prompt_id is None:
            raise ValueError("prompt_id is required for Langfuse prompt management")

        langfuse_client: Final = langfuse_client_init(
            langfuse_public_key=dynamic_callback_params.get("langfuse_public_key"),
            langfuse_secret=dynamic_callback_params.get("langfuse_secret"),
            langfuse_secret_key=dynamic_callback_params.get("langfuse_secret_key"),
            langfuse_host=dynamic_callback_params.get("langfuse_host"),
            allow_env_credentials=dynamic_callback_params.get("langfuse_host") is None,
        )
        langfuse_prompt_client: Final = self._get_prompt_from_id(
            langfuse_prompt_id=prompt_id,
            langfuse_client=langfuse_client,
            prompt_label=prompt_label,
            prompt_version=prompt_version,
        )

        ## SET PROMPT
        compiled_prompt: Final = self._compile_prompt(
            langfuse_prompt_client=langfuse_prompt_client,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Pass the prompt id: add langfuse_prompt_id to callback params / metadata, or the documented prompt_params carrying prompt_id
2. Check for typos in the parameter name that carries the prompt id
3. Optionally also pass prompt_label/prompt_version to pin a specific variant
4. If you meant to send a raw prompt (not a managed one), remove the Langfuse prompt manager from the call

Example fix

# before
response = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    metadata={"prompt_management": "langfuse"},  # ValueError: prompt_id is required
)

# after
response = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    metadata={"prompt_management": "langfuse", "prompt_id": "my-chat-prompt"},
)

def validate_prompt_call(metadata: dict) -> None:
    if metadata.get("prompt_management") == "langfuse" and not metadata.get("prompt_id"):
        raise ValueError("langfuse prompt management requires prompt_id")

When it happens

Trigger: Configuring litellm.prompt_manager = 'langfuse' without supplying prompt_id in the request/callback params (e.g. no langfuse_prompt_id in dynamic callback params or litellm_params); building a PromptSpec whose prompt_id field is left null; calling completion with prompt variables but no prompt id.

Common situations: Copy-pasting a Langfuse prompt-management config that omits the prompt name; assuming the prompt is inferred from the model or messages; typos in the callback param key (e.g. langfuse_prompt_label set but prompt_id forgotten).

Related errors

• Langfuse not installed, try running 'pip install langfu
• 'models' param not in kwargs
• duration needs to be one of ["daily", "weekly", "monthly", "
• Either a chat completion object or the text response needs t
• prompt_id is required for Arize Phoenix prompt manager

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