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

Configuration validation error from the WXO handler's _extract_litellm_params: the 'cp4d_host' key is absent or empty in litellm_params. LiteLLM requires cp4d_host to construct the Cloud Pak for Data base URL for all watsonx Orchestrate agent calls, so it fails fast with a ValueError before any HTTP request is made.

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 6c2dcb801b)

Solutions

Add 'cp4d_host' to the model's litellm_params in config.yaml, e.g. cp4d_host: https://cpd-host:443 (no trailing path).
If using env vars in config, confirm the var (e.g. os.environ/CP4D_HOST) is set and non-empty in the proxy's environment.
Double-check spelling: the key must be exactly 'cp4d_host', not 'host' or 'api_base'.

Example fix

# before
model_info:
  - model_name: my-wxo-agent
    litellm_params:
      model: watsonx_orchestrate/agent
      instance_id: my-instance

# after
model_info:
  - model_name: my-wxo-agent
    litellm_params:
      model: watsonx_orchestrate/agent
      cp4d_host: https://cpd.example.com:443
      instance_id: my-instance

Defensive patterns

Strategy: validation

Validate before calling

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

def validate_wxo_config(litellm_params: dict) -> None:
    missing = [k for k in REQUIRED_WXO_PARAMS if not litellm_params.get(k)]
    if missing:
        raise ConfigError(f"WXO config missing: {missing}")

Type guard

def has_valid_wxo_config(p: dict) -> bool:
    return all(isinstance(p.get(k), str) and p[k].strip() for k in ("cp4d_host", "instance_id", "wxo_agent_id", "api_key"))

Prevention

Define WXO model blocks once in config.yaml and validate them at proxy startup with a config linter.
Use env var indirection (os.environ/VAR) so empty values fail visibly at startup, not at request time.
Keep a checklist of the four required WXO params next to onboarding docs.

When it happens

Trigger: Declaring a WXO model in the LiteLLM proxy config (or calling acompletion with a wxo model) where litellm_params lacks 'cp4d_host', or its value is an empty string/None. Note the check uses `or ''`, so falsy values (empty string, None) all trigger it.

Common situations: Copy-pasting a WXO deployment block from docs and forgetting cp4d_host; using YAML anchors/inheritance where the host variable resolves empty; mixing up 'host' vs 'cp4d_host' key names in config.

Related errors

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