langflow-ai/langflow · error · ValueError

connections contains app_id values not referenced by operati

Error message

connections contains app_id values not referenced by operations: {unused_raw_app_ids}

What it means

API payload validator: every connection declared in provider_data.connections (identified by app_id) must be referenced by at least one operation (add_flows[].app_ids, upsert_tools[].add_app_ids, etc.). Unreferenced connections raise ValueError 'connections contains app_id values not referenced by operations' (422). This keeps the payload explicit — you cannot ship credentials that nothing binds.

Source

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

    upsert_attr_name: str,
) -> None:
    normalized_remove_ids = {str(remove_id).strip() for remove_id in remove_ids if str(remove_id).strip()}
    normalized_upsert_ids = {
        str(getattr(operation, upsert_attr_name, "")).strip()
        for operation in upsert_operations
        if str(getattr(operation, upsert_attr_name, "")).strip()
    }
    conflicts = sorted(normalized_remove_ids.intersection(normalized_upsert_ids))
    if conflicts:
        msg = f"{remove_label} cannot be combined with upsert for the same id: {conflicts}"
        raise ValueError(msg)


def _validate_api_unused_raw_app_ids(*, raw_app_ids: set[str], referenced_app_ids: set[str]) -> None:
    unused_raw_app_ids = sorted(raw_app_ids.difference(referenced_app_ids))
    if unused_raw_app_ids:
        msg = f"connections contains app_id values not referenced by operations: {unused_raw_app_ids}"
        raise ValueError(msg)


def _validate_api_unique_connection_app_ids(*, connections: list[WatsonxApiKeyValueConnectionPayload]) -> None:
    app_id_counts = Counter(connection.app_id for connection in connections)
    duplicates = sorted(app_id for app_id, count in app_id_counts.items() if count > 1)
    if duplicates:
        msg = f"connections contains duplicate app_id values: {duplicates}"
        raise ValueError(msg)


class WatsonxApiDeploymentUpdatePayload(BaseModel):
    """Watsonx provider_data API contract for deployment update operations.

    All operation fields default to empty lists so LLM-only updates
    (changing the model without any tool/connection changes) can be
    expressed without providing operation entries.
    """

View on GitHub (pinned to 976ec789d2)

Solutions

Delete the unreferenced entry from connections, or add its app_id back to some operation's add list.
When removing a binding, remove the connection too if nothing else references it.
Compute referenced ids client-side and filter connections to exactly that set before sending.

Example fix

// before
{"connections": [{"app_id": "c1"}, {"app_id": "c2"}], "upsert_tools": [{"tool_id": "t", "add_app_ids": ["c1"]}]}
// after
{"connections": [{"app_id": "c1"}], "upsert_tools": [{"tool_id": "t", "add_app_ids": ["c1"]}]}

Defensive patterns

Strategy: validation

Validate before calling

referenced = set()
for op in provider_data.get("add_flows", []): referenced.update(op.get("app_ids", []))
for op in provider_data.get("upsert_tools", []): referenced.update(op.get("add_app_ids", []))
provider_data["connections"] = [c for c in provider_data.get("connections", []) if c["app_id"] in referenced]

Type guard

def all_connections_referenced(provider_data: dict) -> bool:
    referenced = {a for op in provider_data.get("add_flows", []) for a in op.get("app_ids", [])}
    referenced |= {a for op in provider_data.get("upsert_tools", []) for a in op.get("add_app_ids", [])}
    return all(c["app_id"] in referenced for c in provider_data.get("connections", []))

Prevention

Derive connections from the operations that reference them, not the reverse.
When unbinding an app everywhere, also drop its connection entry.
Compute referenced app_ids client-side and filter connections to that set pre-send.

When it happens

Trigger: POST/PATCH a wxO deployment whose connections[] includes an app_id not used by any add_flows/upsert_flows/upsert_tools operation in the same request.

Common situations: Removing a tool's add_app_ids in the UI but leaving its connection in the list; pre-declaring connections 'for later'; editing a previously-valid payload and deleting one add_app_ids reference.

Related errors

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