BerriAI/litellm · error · Exception

Failed to get branches: {e}

Error message

Failed to get branches: {e}

What it means

Catch-all from BitBucketClient.get_branches: the GET to /2.0/repositories/{workspace}/{repo}/refs/branches failed with a non-2xx status or its JSON could not be parsed. Unlike list_files_in_directory, this method has no per-status branching — every failure becomes the same wrapped Exception. Note it returns only the first page of branches (data['values']) since no pagination is followed.

Source

Thrown at litellm/integrations/bitbucket/bitbucket_client.py:210

            return False

    def get_branches(self) -> list[dict[str, Any]]:
        """
        Get list of branches in the repository.

        Returns:
            List of branch information dictionaries
        """
        url: Final = f"{self.base_url}/repositories/{self.workspace}/{self.repository}/refs/branches"

        try:
            response: Final = self.http_handler.get(url, headers=self.headers)
            response.raise_for_status()

            data: Final = response.json()
            return data.get("values", [])
        except Exception as e:
            raise Exception(f"Failed to get branches: {e}")

    def get_file_metadata(self, file_path: str) -> dict[str, Any] | None:
        """
        Get metadata about a file (size, last modified, etc.).

        Args:
            file_path: Path to the file in the repository

        Returns:
            Dictionary containing file metadata, or None if file not found
        """
        safe_path: Final = _sanitize_file_path(file_path)
        url: Final = f"{self.base_url}/repositories/{self.workspace}/{self.repository}/src/{self.branch}/{safe_path}"

        try:
            # Use GET with Range header to get just the headers (HEAD equivalent)
            headers: Final = self.headers.copy()
            headers["Range"] = "bytes=0-0"  # Request only first byte to get headers

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Confirm credentials and slugs with get_repository_info()/test_connection() before calling get_branches()
  2. Extract the status from the message: 404 usually means wrong workspace/repo slug
  3. If you need all branches in a large repo, page through pagelen/next links yourself — this client only returns page one
  4. Retry on transient 5xx with backoff

Example fix

# before
branches = client.get_branches()

# after
if not client.test_connection():
    raise RuntimeError("BitBucket connection failed; check config")
branches = client.get_branches()
branch_names = [b["name"] for b in branches]
Defensive patterns

Strategy: try-catch

Validate before calling

if not client.test_connection():
    raise RuntimeError("Cannot list branches: BitBucket connection failed")

Try / catch

try:
    branches = client.get_branches()
except Exception as e:
    if "404" in str(e):
        branches = []  # wrong slug or empty repo
    else:
        raise

Prevention

When it happens

Trigger: Calling get_branches() with credentials lacking repository read scope, when the repository has no branches or was emptied, or when the workspace slug is wrong. Also triggered by any 5xx or network error since all exceptions collapse into this one message.

Common situations: Validating that a configured branch exists before pointing the client at it; newly created empty repositories; tokens scoped to a single branch via branch restrictions.

Related errors

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