BerriAI/litellm · error · ValueError

'instance_id' is required in litellm_params for WXO agents

Error message

'instance_id' is required in litellm_params for WXO agents

What it means

Watsonx Orchestrate runs inside a named instance (space/project) on the CP4D platform, and every agent API call embeds instance_id in the path. _extract_litellm_params() therefore requires a non-empty instance_id in litellm_params and raises this ValueError when it is missing or blank. No HTTP request is attempted — this is a config-validation failure.

Solutions

Find the instance id in Watsonx Orchestrate (the instance/space identifier in the agent API URL) and add instance_id to litellm_params
Verify the other required keys (cp4d_host, wxo_agent_id, api_key) are present in the same block
Check for typos: instance-id or instanceId are not read
Reload the proxy config after the change

Example fix

# before
litellm_params:
  model: watsonx_orchestrate/my-agent
  cp4d_host: https://cp4d.example.com
  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: 6c9b...,        # from the WXO agent API path
  wxo_agent_id: my-agent
  api_key: os.environ/WXO_API_KEY

Defensive patterns

Strategy: validation

Validate before calling

def validate_wxo_instance(litellm_params: dict) -> None:
    if not litellm_params.get("instance_id"):
        raise ValueError("watsonx_orchestrate deployment requires instance_id from the WXO agent API path")

Try / catch

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

Prevention

Extract instance_id from the agent API URL shown in Watsonx Orchestrate, not from memory
Store the full set of WXO identifiers together in one secret/config object
Validate the config in CI before deploying

When it happens

Trigger: A watsonx_orchestrate deployment missing the instance_id key; instance_id left as an empty string; env-var-backed instance_id resolving to unset; confusing instance_id with the space/project name from the WXO UI.

Common situations: Copying the agent URL from the WXO UI but not extracting the instance/space id; provisioning scripts that template most params but skip instance_id; renaming environments so the old instance id is dropped.

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/71f16c07d3238fb9. Report an issue: GitHub.

Appendix: source

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

                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
    async def handle_non_streaming(
        request_id: str,

View on GitHub (pinned to 77b7c6c40c)