BerriAI/litellm · error · ValueError

prompt_id or prompt_spec is required

Error message

prompt_id or prompt_spec is required

What it means

Raised by GenericPromptManager._fetch_prompt_from_api (sync path) when both prompt_id and prompt_spec are None. The manager needs at least one identifier to know which prompt to request from the /beta/litellm_prompt_management endpoint.

Source

Thrown at litellm/integrations/generic_prompt_management/generic_prompt_manager.py:109

        if self.api_key:
            headers["Authorization"] = f"Bearer {self.api_key}"
        return headers

    def _fetch_prompt_from_api(self, prompt_id: str | None, prompt_spec: PromptSpec | None) -> dict[str, Any]:
        """
        Fetch a prompt from the API.

        Args:
            prompt_id: The ID of the prompt to fetch

        Returns:
            The prompt data from the API

        Raises:
            Exception: If the API request fails
        """
        if prompt_id is None and prompt_spec is None:
            raise ValueError("prompt_id or prompt_spec is required")

        url: Final = f"{self.api_base}/beta/litellm_prompt_management"
        params: Final = {
            "prompt_id": prompt_id,
            **(self.additional_provider_specific_query_params or {}),
        }
        http_client: Final = _get_httpx_client()

        try:
            response: Final = http_client.get(
                url,
                params=params,
                headers=self._get_headers(),
            )

            response.raise_for_status()
            return response.json()
        except httpx.HTTPError as e:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Set prompt_id in the model's litellm_params (e.g. prompt_id: my-prompt-id) so the prompt can be resolved.
2. Alternatively supply a complete PromptSpec (with its own litellm_params including prompt_id) so prompt_spec is not None.
3. Verify you are not shadowing the value: a prompt_id set on the wrong nesting level (e.g. under model_info instead of litellm_params) reads as None.

Example fix

// before
litellm_params:
  model: openai/gpt-4o
  prompt_integration: generic_api
  api_base: https://proxy.example.com
  // prompt_id missing

// after
litellm_params:
  model: openai/gpt-4o
  prompt_integration: generic_api
  api_base: https://proxy.example.com
  prompt_id: my-prompt-id

def validate_prompt_identifier(prompt_id: str | None, prompt_spec) -> None:
    if prompt_id is None and prompt_spec is None:
        raise ValueError("Configure prompt_id (or a full prompt_spec) on the prompt-management model")

When it happens

Trigger: Calling compile_prompt_helper(prompt_id=None, prompt_spec=None); configuring a prompt-management model whose litellm_params has neither prompt_id nor a prompt_spec; a PromptSpec object that fails to carry a prompt_id through to the fetch call.

Common situations: Omitting 'prompt_id' in the model's litellm_params in config.yaml; passing a model_info block for prompt integration but leaving the identifier fields empty during initial setup or after renaming the field.

Related errors

• prompt_id is required for Arize Phoenix prompt manager
• api_base is required in generic_prompt_config
• gitlab_config is required for gitlab prompt integration
• project and access_token are required
• prompt_id is required for GitLab prompt manager

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