langflow-ai/langflow · error · ValueError

existing_agent_id is only for tracking existing wxO agents i

Error message

existing_agent_id is only for tracking existing wxO agents in Langflow and cannot include fields that update the wxO agent. Update the deployment after it is tracked.

What it means

Model validator on WatsonxApiDeploymentCreatePayload: when existing_agent_id is provided, it must be the ONLY field set in provider_data — Langflow merely tracks the existing wxO agent and must not be asked to modify it at create time. Any additional field (display_name, llm, add_flows, connections, ...) raises ValueError with guidance to update the deployment after it is tracked (422).

Source

Thrown at src/backend/base/langflow/api/v1/mappers/deployments/watsonx_orchestrate/payloads.py:379

        default=None,
        description=(
            "Provider-owned agent id to track in Langflow instead of creating a new wxO agent. "
            "When provided, the request must not include fields that would update the wxO agent."
        ),
    )

    @model_validator(mode="after")
    def validate_create_operation_requirements(self) -> WatsonxApiDeploymentCreatePayload:
        if "existing_agent_id" in self.model_fields_set:
            if self.existing_agent_id is None:
                msg = "provider_data.existing_agent_id cannot be set to null."
                raise ValueError(msg)
            if len(self.model_fields_set) > 1:
                msg = (
                    "existing_agent_id is only for tracking existing wxO agents in Langflow and cannot include "
                    "fields that update the wxO agent. Update the deployment after it is tracked."
                )
                raise ValueError(msg)
            return self
        if self.display_name is None:
            msg = "provider_data.display_name is required for new agent creation."
            raise ValueError(msg)
        if self.llm is None:
            msg = "provider_data.llm is required for new agent creation."
            raise ValueError(msg)
        # TODO: Allow wxO agent creation without initial flows/tools once the adapter create path supports it.
        if not (self.add_flows or self.upsert_tools):
            msg = "provider_data must include at least one add_flows or upsert_tools item for new agent creation."
            raise ValueError(msg)
        _validate_api_unique_connection_app_ids(connections=self.connections)
        raw_app_ids = {raw.app_id for raw in self.connections}
        referenced_app_ids = _collect_api_referenced_app_ids(self.add_flows, attr_name="app_ids")
        referenced_app_ids.update(_collect_api_referenced_app_ids(self.upsert_tools, attr_name="add_app_ids"))
        _validate_api_unused_raw_app_ids(raw_app_ids=raw_app_ids, referenced_app_ids=referenced_app_ids)
        return self

View on GitHub (pinned to 976ec789d2)

Solutions

Send provider_data with exactly one key: {"existing_agent_id": "<wxo-agent-id>"}.
To modify the agent (flows, tools, llm, display name), first create the tracked deployment, then issue a deployment update.
Reset the create form / payload builder to a minimal object when tracking mode is selected.

Example fix

// before
{"provider_data": {"existing_agent_id": "agent-1", "display_name": "My agent", "add_flows": [...]}}
// after
{"provider_data": {"existing_agent_id": "agent-1"}}

Defensive patterns

Strategy: validation

Validate before calling

if provider_data.get("existing_agent_id") is not None:
    provider_data = {"existing_agent_id": provider_data["existing_agent_id"]}  # sole key allowed

Type guard

const isTrackOnlyPayload = (pd: Record<string, unknown>): boolean =>
  pd.existing_agent_id !== undefined && Object.keys(pd).length === 1;

Prevention

When tracking an existing agent, build provider_data from scratch with exactly one key.
Modify tracked agents via deployment update, never via create.
Add a client unit test asserting track-mode payloads contain only existing_agent_id.

When it happens

Trigger: POST /deployments with provider_data containing existing_agent_id together with any other field such as display_name, llm, add_flows, or upsert_tools.

Common situations: Reusing a full create-payload template and just adding existing_agent_id; UI not switching to 'track existing agent' mode; misunderstanding that tracking is a distinct, minimal operation.

Related errors

AI-assisted analysis of langflow-ai/langflow@976ec789d2 (2026-08-14). Data as JSON: /api/errors/ffb818f9b932b1d6. Report an issue: GitHub.