{"record":{"id":"71f16c07d3238fb9","repo":"BerriAI/litellm","slug":"instance-id-is-required-in-litellm-params-for-wx","errorCode":null,"errorMessage":"'instance_id' is required in litellm_params for WXO agents","messagePattern":"'instance_id' is required in litellm_params for WXO agents","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/a2a_protocol/providers/watsonx_orchestrate/handler.py","lineNumber":199,"sourceCode":"                event = json.loads(data_str)\n            except json.JSONDecodeError:\n                continue\n            chunk_text = WatsonxOrchestrateTransformation.extract_text_from_wxo_result(event)\n            if chunk_text:\n                accumulated_text += chunk_text\n        return accumulated_text\n\n    @staticmethod\n    def _extract_litellm_params(litellm_params: dict[str, Any]) -> WXORequestParams:\n        cp4d_host: Final = litellm_params.get(\"cp4d_host\") or \"\"\n        instance_id: Final = litellm_params.get(\"instance_id\") or \"\"\n        wxo_agent_id: Final = litellm_params.get(\"wxo_agent_id\") or \"\"\n        api_key: Final = litellm_params.get(\"api_key\") or \"\"\n\n        if not cp4d_host:\n            raise ValueError(\"'cp4d_host' is required in litellm_params for WXO agents\")\n        if not instance_id:\n            raise ValueError(\"'instance_id' is required in litellm_params for WXO agents\")\n        if not wxo_agent_id:\n            raise ValueError(\"'wxo_agent_id' is required in litellm_params for WXO agents\")\n        if not api_key:\n            raise ValueError(\"'api_key' is required in litellm_params for WXO agents\")\n\n        return WXORequestParams(\n            cp4d_host=cp4d_host,\n            instance_id=instance_id,\n            wxo_agent_id=wxo_agent_id,\n            api_key=api_key,\n            username=litellm_params.get(\"username\") or None,\n            auth_mode=litellm_params.get(\"auth_mode\") or \"cp4d\",\n            thread_id=litellm_params.get(\"thread_id\") or None,\n        )\n\n    @staticmethod\n    async def handle_non_streaming(\n        request_id: str,","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/a2a_protocol/providers/watsonx_orchestrate/handler.py#L181-L217","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nlitellm_params:\n  model: watsonx_orchestrate/my-agent\n  cp4d_host: https://cp4d.example.com\n  wxo_agent_id: my-agent\n  api_key: os.environ/WXO_API_KEY\n\n# after\nlitellm_params:\n  model: watsonx_orchestrate/my-agent\n  cp4d_host: https://cp4d.example.com\n  instance_id: 6c9b...,        # from the WXO agent API path\n  wxo_agent_id: my-agent\n  api_key: os.environ/WXO_API_KEY\n","handlingStrategy":"validation","validationCode":"def validate_wxo_instance(litellm_params: dict) -> None:\n    if not litellm_params.get(\"instance_id\"):\n        raise ValueError(\"watsonx_orchestrate deployment requires instance_id from the WXO agent API path\")\n","typeGuard":null,"tryCatchPattern":"try:\n    result = await WatsonxOrchestrateHandler.handle_request(params)\nexcept ValueError as e:\n    if \"'instance_id' is required\" in str(e):\n        raise HTTPException(500, \"WXO deployment missing instance_id\") from e\n    raise\n","preventionTips":["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"],"tags":["watsonx-orchestrate","instance-id","configuration","required-param"],"backgroundTag":"missing-required-argument","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}