langflow-ai/langflow · warning · HTTPException

Invalid flow_id: not a valid UUID.

Error message

Invalid flow_id: not a valid UUID.

What it means

Raised by _validate_flow_access when AssistantRequest.flow_id is supplied but cannot be parsed as a UUID by Python's UUID constructor. The flow_id is used to seed the FLOW_ID global variable for flow execution, so it must be a canonical UUID string. HTTP 422.

Source

Thrown at src/backend/base/langflow/agentic/api/router.py:156

async def _validate_flow_access(flow_id: str | None, user_id: UUID, session: AsyncSession) -> None:
    """Reject an unknown or not-owned flow_id before the model is invoked.

    A missing flow_id is allowed (the assistant runs with no canvas context).
    A supplied id must reference a flow the caller can access, mirroring the
    per-user 404 of the /run and webhook endpoints; not-found and cross-user
    both surface 404 so a flow's existence is not leaked by id.
    """
    if not flow_id:
        return

    from langflow.services.database.models.flow import Flow

    try:
        flow_uuid = UUID(flow_id)
    except ValueError as exc:
        raise HTTPException(status_code=422, detail="Invalid flow_id: not a valid UUID.") from exc

    flow = await session.get(Flow, flow_uuid)
    if flow is None or (flow.user_id is not None and str(flow.user_id) != str(user_id)):
        raise HTTPException(status_code=404, detail="Flow not found.")


@router.post("/execute/{flow_name}", dependencies=[Depends(require_agentic_experience)])
async def execute_named_flow(
    flow_name: str,
    request: AssistantRequest,
    current_user: CurrentActiveUser,
    session: DbSession,
) -> dict:
    """Execute a named flow from the flows directory.

    Named assistant flows embed an Agent that needs provider/model/api-key
    context. Resolving it here (instead of running the raw file) turns a
    silent 500 into a successful run, or a clear 4xx when no provider is set.

View on GitHub (pinned to 976ec789d2)

Solutions

1. Send the flow's actual UUID (from the flow's URL or GET /api/v1/flows) in flow_id.
2. Omit flow_id entirely when no canvas flow context is needed — the validator returns early for empty values.
3. In JS clients, guard against 'undefined'/'null' stringification before building the payload.

Example fix

// before
body: JSON.stringify({input_value: q, flow_id: flowName}) // 'my assistant flow'
// after
body: JSON.stringify({input_value: q, flow_id: flowId}) // '3fa85f64-5717-4562-b3fc-2c963f66afa6'

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const safeFlowId = (id) => (id && UUID_RE.test(id) ? id : undefined); // omit invalid instead of sending

function isUuidString(s: string): boolean {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s);
}

On 422 'Invalid flow_id', strip flow_id from the payload and retry once without canvas context.

When it happens

Trigger: POST /api/v1/agentic/assist* with flow_id set to a non-UUID string, e.g. a flow name ("my-flow"), an integer id, a UUID missing dashes, or a value with surrounding whitespace/typo.

Common situations: Client sends the flow's display name or slug instead of its id; copying an id with a truncated character; passing a null-ish placeholder like "undefined" or "null" from JavaScript when the flow was never selected.

Related errors

• Invalid flow_id: not a valid UUID.
• Invalid path
• Provider '{provider}' is not configured. Available providers
• Could not extract class name from code
• Inputs and outputs have overlapping names: {overlap}

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