BerriAI/litellm · error · ValueError

bitbucket_config is required for BitBucket prompt integratio

Error message

bitbucket_config is required for BitBucket prompt integration

What it means

The BitBucket prompt integration's prompt_initializer reads bitbucket_config from litellm_params via getattr; if it is absent or falsy it raises ValueError before constructing BitBucketPromptManager. bitbucket_config is a dict holding workspace, repository, access_token (and optionally branch, auth_method, username) and must be attached to the request's litellm_params.

Source

Thrown at litellm/integrations/bitbucket/__init__.py:41

                - workspace: BitBucket workspace name
                - repository: Repository name
                - access_token: BitBucket access token
                - branch: Branch to fetch prompts from (default: main)
    """
    import litellm

    litellm.global_bitbucket_config = config


def prompt_initializer(litellm_params: "PromptLiteLLMParams", prompt_spec: "PromptSpec") -> "CustomPromptManagement":
    """
    Initialize a prompt from a BitBucket repository.
    """
    bitbucket_config: Final = getattr(litellm_params, "bitbucket_config", None)
    prompt_id: Final = getattr(litellm_params, "prompt_id", None)

    if not bitbucket_config:
        raise ValueError("bitbucket_config is required for BitBucket prompt integration")

    try:
        bitbucket_prompt_manager: Final = BitBucketPromptManager(
            bitbucket_config=bitbucket_config,
            prompt_id=prompt_id,
        )

        return bitbucket_prompt_manager
    except Exception as e:
        raise e


prompt_initializer_registry: Final = {
    SupportedPromptIntegrations.BITBUCKET.value: prompt_initializer,
}

# Export public API
__all__ = [

View on GitHub (pinned to 6c2dcb801b)

Solutions

Add bitbucket_config to litellm_params with at least workspace, repository, and access_token
Check spelling and nesting level — it must be exactly the key bitbucket_config readable by getattr on litellm_params
Pass prompt_id alongside the config so the manager knows which .prompt file to load
Verify the surrounding try/except did not swallow an earlier error from BitBucketPromptManager construction (the code re-raises as-is)

Example fix

# before
litellm_params = {"model": "gpt-4o"}  # no bitbucket_config -> ValueError

# after
litellm_params = {
    "model": "gpt-4o",
    "prompt_id": "my-prompt",
    "bitbucket_config": {
        "workspace": "my-workspace",
        "repository": "my-repo",
        "access_token": "<token>",
        "branch": "main",
    },
}

Defensive patterns

Strategy: validation

Validate before calling

REQUIRED_BB_KEYS = ("workspace", "repository", "access_token")

def validate_bitbucket_config(params: dict) -> dict:
    cfg = params.get("bitbucket_config")
    if not isinstance(cfg, dict) or not all(cfg.get(k) for k in REQUIRED_BB_KEYS):
        raise ValueError("bitbucket_config must include workspace, repository, access_token")
    if not params.get("prompt_id"):
        raise ValueError("prompt_id is required for BitBucket prompts")
    return cfg

Type guard

def is_valid_bitbucket_config(cfg) -> bool:
    return (
        isinstance(cfg, dict)
        and all(isinstance(cfg.get(k), str) and cfg[k].strip() for k in ("workspace", "repository", "access_token"))
    )

Try / catch

try:
    litellm.completion(**request_params)
except ValueError as e:
    if "bitbucket_config is required" in str(e):
        raise ConfigError("Add bitbucket_config to this model's litellm_params") from e
    raise

Prevention

Validate bitbucket_config keys and prompt_id in one pre-flight function
Keep the config key name exact: bitbucket_config under litellm_params
In proxy YAML, lint the model entry for phoenix/bitbucket prompt models at deploy time

When it happens

Trigger: Configuring a BitBucket-hosted prompt model without a bitbucket_config block; passing bitbucket_config as None/empty dict; key misspelled (e.g. bitbucketCfg or nested one level too deep); config attached to the wrong level (model_settings instead of litellm_params).

Common situations: First-time setup following the prompts docs but omitting the config dict; proxy YAML indentation placing bitbucket_config under the wrong section; migration from another prompt integration where config lived elsewhere.

Related errors

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