BerriAI/litellm · error · ValueError

prompt_id is required for BitBucket prompt manager

Error message

prompt_id is required for BitBucket prompt manager

What it means

ValueError raised at the top of the sync _compile_prompt_helper: BitBucket prompt compilation is meaningless without a prompt_id because templates are keyed by file name, and unlike database-backed prompt managers there is no prompt_spec fallback to derive one from. Passing prompt_id=None is treated as a caller bug, not a runtime failure.

Source

Thrown at litellm/integrations/bitbucket/bitbucket_prompt_manager.py:443

        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 a BitBucket prompt template into a PromptManagementClient structure.

        This method:
        1. Loads the prompt template from BitBucket
        2. Renders it with the provided variables
        3. Converts the rendered text into chat messages
        4. Extracts model and optional parameters from metadata
        """
        if prompt_id is None:
            raise ValueError("prompt_id is required for BitBucket prompt manager")

        try:
            # Load the prompt from BitBucket if not already loaded
            if prompt_id not in self.prompt_manager.prompts:
                self.prompt_manager._load_prompt_from_bitbucket(prompt_id)

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

            # Convert rendered content to chat messages
            messages: Final = self._parse_prompt_to_messages(rendered_prompt)

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

            # Extract optional parameters from metadata
            optional_params: Final = {}
            for param in [

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Always pass a concrete prompt_id string matching a .prompt file name in the repository
2. Validate at the call site before invoking: if prompt_id is None: raise early with your own context
3. Check request/config parsing for misspelled keys that silently default to None
4. If you meant to use a DB-backed prompt, use the PromptManagementClient path that accepts prompt_spec instead

Example fix

# before
result = await client.async_compile_prompt_helper(None, vars, dynamic_params)

# after
if prompt_id is None:
    raise ValueError("Request is missing 'prompt' id; BitBucket prompts require it")
result = await client.async_compile_prompt_helper(prompt_id, vars, dynamic_params)

def require_prompt_id(prompt_id: str | None) -> str:
    if not isinstance(prompt_id, str) or not prompt_id.strip():
        raise ValueError("Request must include a non-empty BitBucket prompt id")
    return prompt_id.strip()

def is_valid_prompt_id(prompt_id) -> bool:
    return isinstance(prompt_id, str) and bool(prompt_id.strip())

try:
    compiled = client._compile_prompt_helper(prompt_id, variables, dynamic_params)
except ValueError as e:
    if "prompt_id is required" in str(e):
        raise TypeError("Caller bug: prompt_id missing") from e
    raise

When it happens

Trigger: Calling compile_prompt_helper with prompt_id=None and no prompt_spec; forwarding an unset request parameter (e.g. a 'prompt' field absent from the request body) straight into the helper; generic prompt-routing code that handles multiple backends passing None for BitBucket.

Common situations: Shared router code paths where other prompt integrations accept None; config files where the prompt id key is misspelled so it reads as None; API requests missing the prompt field.

Related errors

• Template '{template_id}' not found
• Prompt template '{prompt_id}' not found
• Invalid file path {file_path!r}: path traversal detected
• workspace, repository, and access_token are required
• Failed to load prompt '{prompt_id}' from BitBucket: {e}

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