langflow-ai/langflow · error · ValueError

flow_version_id must be a valid UUID.

Error message

flow_version_id must be a valid UUID.

What it means

The same WatsonxApiCreatedTool validator accepted a string but UUID(value) raised ValueError, meaning the string is not parseable as a UUID. Pydantic UUID fields normally report this as 'value is not a valid uuid'; this custom validator replaces that with an explicit message naming flow_version_id. It fires only for strings (UUID objects and non-strings are handled by the earlier branches).

Source

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

    model_config = {"extra": "forbid"}

    flow_version_id: UUID
    tool_id: NonEmptyString = Field(description="Provider-owned tool identifier.")

    @field_validator("flow_version_id", mode="before")
    @classmethod
    def normalize_flow_version_id(cls, value: Any) -> UUID:
        if isinstance(value, UUID):
            return value
        if not isinstance(value, str):
            msg = "flow_version_id must be provided as a UUID string or UUID object."
            raise ValueError(msg)  # noqa: TRY004
        try:
            return UUID(value)
        except ValueError as exc:
            msg = "flow_version_id must be a valid UUID."
            raise ValueError(msg) from exc


class WatsonxApiDeploymentCreateResultData(BaseModel):
    """Provider-result payload used by Watsonx mapper create shapers."""

    model_config = {"extra": "ignore"}

    name: NonEmptyString = Field(description="Provider technical agent name.")
    display_name: NonEmptyString
    created_app_ids: list[NonEmptyString] = Field(default_factory=list)
    created_tools: list[WatsonxApiCreatedTool] = Field(default_factory=list)

    @classmethod
    def from_provider_result(cls, provider_result: Any) -> WatsonxApiDeploymentCreateResultData:
        return cls.model_validate(provider_result)


class WatsonxApiDeploymentUpdateResultData(BaseModel):

View on GitHub (pinned to 976ec789d2)

Solutions

1. Use the actual UUID returned when the flow version was created (flow_version.id), not a version number.
2. Validate client-side with uuid.UUID(value) (Python) or a UUID regex before sending.
3. Strip whitespace and verify the string has the 8-4-4-4-12 hex format.
4. If you store version ids in config, copy the full UUID from the Langflow API response or DB.

Example fix

# before
payload = {"tool_id": "my-tool", "flow_version_id": "1.2"}  # semantic version, not UUID

# after
import uuid
vid = str(flow_version.id)  # e.g. '550e8400-e29b-41d4-a716-446655440000'
uuid.UUID(vid)  # client-side assertion before sending
payload = {"tool_id": "my-tool", "flow_version_id": vid}

from uuid import UUID

def valid_uuid_string(s: str) -> bool:
    try:
        UUID(s)
        return True
    except (ValueError, AttributeError, TypeError):
        return False

assert valid_uuid_string(flow_version_id) before request

import re
UUID_RE = re.compile(r'^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$')
def is_uuid_string(v: str) -> bool: return bool(UUID_RE.match(v))

try: UUID(value) except ValueError: report which field and show the received value in your own validation layer, so the mapper never sees it.

When it happens

Trigger: Sending flow_version_id as a malformed string: '12345', 'v1.2.3', a version number like '1', a UUID missing dashes/characters, or with surrounding whitespace/copy-paste artifacts.

Common situations: Confusing the flow's semantic version ('1.0.0') or an integer version number with the UUID version id; truncating the UUID during logging/copy; building the payload from user-typed input without validation.

Related errors

• flow_version_id must be provided as a UUID string or UUID ob
• provider_data must include exactly one of 'input' or 'messag
• Invalid flow_id: not a valid UUID.
• Invalid flow_id: not a valid UUID.
• actions must be strings

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