Which Nginx Directives Fix n8n WebSocket Disconnections?

The core directives required for n8n WebSockets are proxy_http_version 1.1 and the Upgrade and Connection header mappings. We run high-concurrency automation workloads on our platform at Hostna and frequently see these connections drop if timeouts are not tuned for the specific heartbeat patterns of the n8n editor. Without these settings, the editor will frequently show a lost connection message, even if the underlying workflows continue to execute correctly.

The Necessity of HTTP/1.1 for WebSocket Handshakes

WebSockets rely on the HTTP Upgrade mechanism to transition a standard web connection into a persistent, bidirectional stream. By default, Nginx uses HTTP/1.0 for upstream communication, which does not support the Upgrade header. To fix this, you must explicitly set proxy_http_version 1.1; within your location block. This ensures that the handshake initiated by the n8n frontend is correctly passed to the Node.js backend.

When the browser attempts to establish a WebSocket protocol connection, it sends a header Upgrade: websocket. If Nginx is not configured to pass this header, the backend never receives the request to switch protocols, and the connection remains a standard HTTP request that eventually times out or is rejected by the application. This is why a dedicated server resources environment often requires manual tuning of these proxy headers to ensure the automation engine remains responsive.

Mapping the Connection Header Dynamically

A common mistake in Nginx configuration is hardcoding the Connection header as "upgrade". While this works for WebSocket traffic, it can interfere with standard HTTP requests that do not require an upgrade. The most reliable way to handle this is via a map block in your main Nginx configuration file, typically located at /etc/nginx/nginx.conf.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

This block checks the $http_upgrade variable. If it is empty (standard HTTP), it sets the Connection header to close. If it contains a value (WebSocket), it sets it to upgrade. Inside your site configuration, you then use proxy_set_header Connection $connection_upgrade;. This dynamic approach ensures compatibility across all types of traffic hitting your n8n instance. When deploying a specialized n8n environment, implementing this mapping is a critical step in the setup process.

Tuning Timeouts for Long-Running Workflows

The default Nginx proxy_read_timeout is 60 seconds. In the context of n8n, this is often insufficient. If a workflow execution takes longer than a minute to return data to the editor, or if the WebSocket heartbeat is delayed, Nginx will terminate the connection. Setting proxy_read_timeout 3600s ensures that long-running workflows do not cause the Nginx worker to close the upstream connection prematurely after the default 60-second window.

Similarly, proxy_send_timeout should be adjusted to match. These high values are safe for automation servers where persistent connections are expected. If you are using a standard web hosting plan, you may find these timeouts restricted, which is why a virtual or dedicated environment is preferred for n8n. These parameters configured within the Hostna dashboard allow for the stability required by complex automation chains.

Buffer Sizes and Large Workflow Payloads

n8n workflows are stored and transmitted as large JSON objects. When you open a complex workflow in the editor, the backend sends a significant amount of data. If the Nginx proxy buffers are too small, the proxy may fail to handle the response, leading to 502 Bad Gateway errors or truncated data. A machine with 4 GB of RAM typically handles the default proxy_buffer_size of 4k or 8k, but n8n’s large JSON payloads in the editor often require increasing this to 128k to avoid 502 errors.

Adding the following directives to your location block can mitigate these issues:

proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

Furthermore, proxy_buffering off; is highly recommended for n8n. This directive allows Nginx to pass data from the backend to the client as soon as it is received, rather than waiting for the buffer to fill. This is particularly important for real-time execution updates in the n8n UI, where handling sensitive workflow data requires immediate feedback.

Environment Variables and Proxy Hops

Beyond the Nginx configuration, n8n itself needs to know it is sitting behind a proxy. The N8N_PROXY_HOPS variable must be set to 1 if your Nginx proxy is the only hop before the application, ensuring that X-Forwarded-For correctly identifies the client IP for security logging. If you have an additional layer, such as a global load balancer, this number should be increased accordingly.

Failing to set this correctly can lead to issues with protocol detection. If n8n does not recognize the proxy, it may attempt to generate internal links using http instead of https, causing mixed content warnings in the browser. Always ensure that X-Forwarded-Proto $scheme is passed in your Nginx configuration to inform n8n of the encryption status of the external connection. This is a fundamental part of securing your automation workflows.

Troubleshooting the Handshake with Command Line Tools

If the editor still reports a connection loss, you can verify the WebSocket handshake manually using curl. A successful handshake should return an HTTP/1.1 101 Switching Protocols response. You can test this by targeting the /rest/push endpoint, which n8n uses for its WebSocket communication.

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: your-domain.com" -H "Origin: https://your-domain.com" https://your-domain.com/rest/push

If you receive a 200 OK instead of a 101, Nginx is not correctly passing the Upgrade header. If you receive a 502, check the Nginx error logs at /var/log/nginx/error.log. Often, the error log will explicitly state that the upstream sent a response that was too large for the current buffer, confirming that proxy_buffer_size needs adjustment. For further assistance, refer to the technical documentation for your machine or the official Nginx WebSocket documentation for advanced tuning options.

In cases where the configuration appears correct but disconnections persist, inspect the browser’s developer console. WebSocket errors are often logged with specific codes. A code 1006 usually indicates an abnormal closure, which is almost always tied to a timeout in the proxy layer or a network firewall. Adjusting the keepalive_timeout and proxy_read_timeout directives usually resolves these persistent disconnections.

This article was drafted with AI assistance from Hostna’s own research pipeline and published without individual review. Tell us if anything here is wrong.