BerriAI/litellm · error · ValueError

'cp4d_host' is required in litellm_params for WXO agents

Error message

'cp4d_host' is required in litellm_params for WXO agents

What it means

_extract_litellm_params() validates the deployment metadata for Watsonx Orchestrate agents before any request is made. cp4d_host (the Cloud Pak for Data / WXO base URL) is mandatory; an empty or missing value raises this ValueError immediately. All WXO routing and token URLs are derived from this host, so the handler cannot proceed without it.

Solutions

Add cp4d_host (e.g. https://cp4d.example.com) to the WXO deployment's litellm_params
If using os.environ/..., confirm the variable is set in the proxy's runtime environment
Use the exact key name cp4d_host and keep it inside litellm_params
Restart/reload the proxy after fixing config.yaml

Example fix

# before (config.yaml)
litellm_params:
  model: watsonx_orchestrate/my-agent
  instance_id: my-instance
  wxo_agent_id: my-agent
  api_key: os.environ/WXO_API_KEY

# after
litellm_params:
  model: watsonx_orchestrate/my-agent
  cp4d_host: https://cp4d.example.com
  instance_id: my-instance
  wxo_agent_id: my-agent
  api_key: os.environ/WXO_API_KEY

Defensive patterns

Strategy: validation

Validate before calling

REQUIRED_WXO_KEYS = ("cp4d_host", "instance_id", "wxo_agent_id", "api_key")

def validate_wxo_deployment(litellm_params: dict) -> None:
    missing = [k for k in REQUIRED_WXO_KEYS if not litellm_params.get(k)]
    if missing:
        raise ValueError(f"watsonx_orchestrate deployment missing: {', '.join(missing)}")

Try / catch

try:
    result = await WatsonxOrchestrateHandler.handle_request(params)
except ValueError as e:
    if "'cp4d_host' is required" in str(e):
        raise HTTPException(500, "WXO deployment missing cp4d_host") from e
    raise

Prevention

Template WXO deployments from one validated example containing all four required keys
Check env vars backing cp4d_host at proxy startup
Run the config through a YAML linter that understands watsonx_orchestrate requirements

When it happens

Trigger: A watsonx_orchestrate deployment in config.yaml whose litellm_params omits cp4d_host; cp4d_host sourced from an unset env var so it resolves to empty; a typo like cp4d-url: leaving the real key absent.

Common situations: First-time WXO agent setup in the LiteLLM proxy; copying an example config and deleting the host line; env var name drift between environments (WXO_HOST vs CP4D_HOST); secrets-management templates that render the key only in some environments.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/24d7232bb1320624. Report an issue: GitHub.

Appendix: source

Thrown at litellm/a2a_protocol/providers/watsonx_orchestrate/handler.py:197

                continue
            try:
                event = json.loads(data_str)
            except json.JSONDecodeError:
                continue
            chunk_text = WatsonxOrchestrateTransformation.extract_text_from_wxo_result(event)
            if chunk_text:
                accumulated_text += chunk_text
        return accumulated_text

    @staticmethod
    def _extract_litellm_params(litellm_params: dict[str, Any]) -> WXORequestParams:
        cp4d_host: Final = litellm_params.get("cp4d_host") or ""
        instance_id: Final = litellm_params.get("instance_id") or ""
        wxo_agent_id: Final = litellm_params.get("wxo_agent_id") or ""
        api_key: Final = litellm_params.get("api_key") or ""

        if not cp4d_host:
            raise ValueError("'cp4d_host' is required in litellm_params for WXO agents")
        if not instance_id:
            raise ValueError("'instance_id' is required in litellm_params for WXO agents")
        if not wxo_agent_id:
            raise ValueError("'wxo_agent_id' is required in litellm_params for WXO agents")
        if not api_key:
            raise ValueError("'api_key' is required in litellm_params for WXO agents")

        return WXORequestParams(
            cp4d_host=cp4d_host,
            instance_id=instance_id,
            wxo_agent_id=wxo_agent_id,
            api_key=api_key,
            username=litellm_params.get("username") or None,
            auth_mode=litellm_params.get("auth_mode") or "cp4d",
            thread_id=litellm_params.get("thread_id") or None,
        )

    @staticmethod

View on GitHub (pinned to 77b7c6c40c)