The WebSocket protocol provides real-time bidirectional communication between the ComfyUI server and connected clients. It is the primary mechanism for delivering live execution progress updates, node status changes, preview images, and system events to the web UI and other clients. This document describes the WebSocket message format, connection lifecycle, and supported event types.
For information about REST API endpoints for submitting workflows and querying system state, see REST API Reference
Sources: server.py60-61 protocol.py1-60
The WebSocket server listens at the /ws endpoint and handles connections through the websocket_handler function in the PromptServer class server.py465-538
Title: WebSocket Connection Flow
Sources: server.py465-538
The WebSocket connection accepts an optional clientId query parameter:
clientId: Reuses an existing session by removing the old WebSocket and creating a new one with the same session ID server.py469-474clientId: Generates a new random session ID using uuid.uuid4().hex server.py474-475Sources: server.py469-479
The server maintains two dictionaries for each connected client server.py448-449:
| Dictionary | Purpose | Structure |
|---|---|---|
self.sockets | Stores the active WebSocket connection | {sid: WebSocketResponse} |
self.sockets_metadata | Stores client metadata including feature flags | {sid: {"feature_flags": {...}}} |
Sources: server.py448-479
Feature flags allow the server and client to negotiate supported capabilities, enabling graceful degradation and progressive enhancement of functionality based on what each side supports comfy_api/feature_flags.py1-6
Title: Feature Flag Negotiation Logic
Sources: server.py504-528 comfy_api/feature_flags.py100-113
Client to Server:
Server to Client:
The server uses feature flags to determine message format. For example, preview images are sent differently based on whether the client supports supports_preview_metadata comfy_execution/progress.py210-214
Sources: server.py512-527 comfy_api/feature_flags.py100-113
All text messages are JSON objects with at minimum a type field. The server sends messages using the send_sync method server.py540-546
Sent when a client first connects and whenever the queue state changes server.py483
Sent when the executor begins processing a node or when execution finishes execution.py1001-1002 When a prompt finishes, the node field is null.
Sent when a node successfully completes execution, containing the node's output data execution.py978-980
Sent during node execution to report progress (e.g., during sampling) comfy_execution/progress.py162-188
Sent when a node execution fails, including stack traces and node details execution.py1020-1033
Binary messages are used for performance-critical data like preview images. The message type is determined by a header in the binary payload server.py24-25
The BinaryEventTypes class defines the integer constants used in the header protocol.py60:
| Constant | Value | Purpose |
|---|---|---|
UNENCODED_PREVIEW_IMAGE | 1 | Real-time latent previews |
LATENT_PREVIEW_IMAGE | 2 | Encoded latent previews |
Sources: protocol.py60 comfy_execution/progress.py12
Preview images are sent during sampling. If the client does not support supports_preview_metadata, the server sends a binary message comfy_execution/progress.py208-214
Title: Progress and Preview Data Flow
Sources: comfy_execution/progress.py150-220 protocol.py60
The WebUIProgressHandler manages progress updates. It calculates active node states and sends a combined progress_state message to the initiating client comfy_execution/progress.py162-188
Sources: comfy_execution/progress.py17-32
| Method | Purpose | Parameters |
|---|---|---|
send_sync(event, data, sid) | Send a text message to a specific client | event name, data dict, session ID server.py540-546 |
send_socket_catch_exception(function, message) | Wrapper that catches connection errors | async function, message server.py74-79 |
Sources: server.py74-79 server.py540-546
The send_socket_catch_exception function catches common network errors (e.g., BrokenPipeError, ConnectionResetError, aiohttp.ClientError) and logs warnings instead of crashing server.py74-79
| Event Type | Direction | Trigger | Key Fields |
|---|---|---|---|
status | Server → Client | Connection, queue change | exec_info, sid server.py483 |
feature_flags | Bidirectional | First message | Client/server feature sets server.py512 |
executing | Server → Client | Node execution starts/ends | node, prompt_id execution.py1001 |
executed | Server → Client | Node execution completes | node, output, prompt_id execution.py978 |
progress_state | Server → Client | Any node progress update | prompt_id, nodes comfy_execution/progress.py162 |
| Binary preview | Server → Client | Preview image available | 8-byte header + image data comfy_execution/progress.py208 |
Sources: server.py465-538 execution.py900-1050 comfy_execution/progress.py150-220
Refresh this wiki