BerriAI/litellm · error · Exception

Failed to load prompt '{prompt_id}' from BitBucket: {e}

Error message

Failed to load prompt '{prompt_id}' from BitBucket: {e}

What it means

Raised by BitBucketPromptManager._load_prompt_from_bitbucket when fetching or parsing a {prompt_id}.prompt file fails. The inner exception is typically one of the BitBucketClient errors (auth, access denied, network) bubbled up through get_file_content, and this method flattens it into a generic Exception with the prompt_id in the message.

Source

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

            comment_start_string="{#",
            comment_end_string="#}",
        )

        # Load prompts from BitBucket if prompt_id is provided
        if self.prompt_id:
            self._load_prompt_from_bitbucket(self.prompt_id)

    def _load_prompt_from_bitbucket(self, prompt_id: str) -> None:
        """Load a specific .prompt file from BitBucket."""
        try:
            # Fetch the .prompt file from BitBucket
            prompt_content: Final = self.bitbucket_client.get_file_content(f"{prompt_id}.prompt")

            if prompt_content:
                template: Final = self._parse_prompt_file(prompt_content, prompt_id)
                self.prompts[prompt_id] = template
        except Exception as e:
            raise Exception(f"Failed to load prompt '{prompt_id}' from BitBucket: {e}")

    def _parse_prompt_file(self, content: str, prompt_id: str) -> BitBucketPromptTemplate:
        """Parse a .prompt file content and extract metadata and template."""
        # Split frontmatter and content
        if content.startswith("---"):
            parts: Final = content.split("---", 2)
            if len(parts) >= 3:
                frontmatter_str = parts[1].strip()
                template_content = parts[2].strip()
            else:
                frontmatter_str = ""
                template_content = content
        else:
            frontmatter_str = ""
            template_content = content

        # Parse YAML frontmatter
        metadata: dict[str, Any] = {}

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Call bitbucket_client.test_connection() at startup to fail fast on config errors before serving traffic
  2. Confirm {prompt_id}.prompt exists at the repo root (or the path you expect) on the configured branch in the BitBucket UI
  3. Check the inner error text in the message — it carries the underlying HTTP status
  4. Verify the branch config key matches where the prompt files live (default is 'main')

Example fix

# before
manager._load_prompt_from_bitbucket("summary")  # raises on any infra error

# after (startup validation)
if not manager.bitbucket_client.test_connection():
    raise RuntimeError("BitBucket prompt source misconfigured")
manager._load_prompt_from_bitbucket("summary")
Defensive patterns

Strategy: validation

Validate before calling

if not manager.bitbucket_client.test_connection():
    raise RuntimeError("BitBucket prompt source misconfigured; aborting load")
manager._load_prompt_from_bitbucket(prompt_id)

Try / catch

try:
    manager._load_prompt_from_bitbucket(prompt_id)
except Exception as e:
    raise RuntimeError(f"Prompt '{prompt_id}' unavailable from BitBucket: {e}") from e

Prevention

When it happens

Trigger: Requesting a prompt_id whose .prompt file does not exist with credentials that yield 403 instead of 404, expired token (401), wrong branch configured (file exists on main but client points elsewhere), or network failure — any of these aborts the load and re-raises here.

Common situations: First request after deploying the BitBucket prompt integration with incomplete config; prompt file renamed without updating callers; branch set to a feature branch that was deleted after merge.

Related errors

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