This article explains what n8n's /rest/push endpoint does, what a pushRef is, and why you might see repeated connection attempts in your browser's network tab. It also covers the common causes of reconnection loops — stuck browser tabs, misconfigured scripts, and embedded widgets — and walks through how to identify and resolve them.

What is /rest/push?

The /rest/push endpoint is a long-lived connection (either Server-Sent Events or WebSocket, depending on the N8N_PUSH_BACKEND setting) opened from your browser to the main n8n instance. It's what keeps the editor UI feeling live — node-by-node execution progress, status badges, and real-time updates all flow down this single connection.

Every time you open an n8n editor tab, the browser generates a client-side pushRef UUID and opens a connection to /rest/push?pushRef=<id>. The main n8n process holds an in-memory map of pushRef → socket and streams editor events down the matching connection.

What a pushRef represents

  • One pushRef = one browser tab with the editor open.
  • It's generated client-side, so it's unique per tab, not per user.
  • If you open the editor in three tabs, you have three active pushRef connections.

How it fits into queue mode

On Awesomate's hosted n8n (which runs in queue mode), responsibilities are split across processes:

  • Main instance — serves the editor UI and owns all /rest/push connections.
  • Workers — execute workflows. They never talk to browsers and do not expose /rest/push.
  • Redis — provides the Bull job queue and a pub/sub channel for execution events.

Event flow during an execution

  1. The main instance enqueues a job to Redis.
  2. A worker picks it up and executes the workflow.
  3. The worker publishes node and execution events to Redis pub/sub.
  4. The main instance (subscribed to pub/sub) looks up the relevant pushRef and writes the event to that socket.

If Redis becomes degraded, executions still complete on the workers — but the editor goes quiet because events aren't being forwarded back to the browser. This is usually the first symptom customers notice.

Why workers reduce reconnection loops

We run a process on our server that ensures workers keep executing and prevents push connections from timing out. Separating workers from the main process helps in three important ways:

  • Crash isolation — a bad workflow kills a worker, not the main process. Without this split, a crash would drop every open editor tab at once, causing a thundering-herd reconnect.
  • Responsive event loop — heavy execution work doesn't compete with heartbeat and ping handling on the main process, so connections aren't falsely declared dead.
  • Transparent recovery — process supervision (systemd, pm2, Docker, Kubernetes) restarts dead workers automatically. Browsers never see it happen.

Common causes of reconnection loops

Even with workers in place, some reconnection patterns are outside the server's control. These are the ones most likely to appear in customer tickets.

1. Proxy or load balancer idle timeouts

If an upstream proxy (nginx, AWS ALB, Cloudflare) has an idle timeout shorter than the push heartbeat interval, it will silently drop the connection. The browser notices and reconnects — over and over.

  • Idle timeout must exceed the heartbeat interval (check proxy_read_timeout on nginx).
  • WebSocket upgrade headers must be correctly configured if using the WebSocket backend.

2. Horizontally scaled main without sticky sessions

If you run multiple main instances behind a load balancer without sticky sessions, a reconnect can land on a different instance — one that has no record of the original pushRef. The new instance rejects or re-handshakes the connection, and the loop continues.

3. Client-side issues

  • Stuck background tabs — an editor tab left open for days in the background can end up in a reconnect loop, especially after the laptop sleeps.
  • Embedded chat widgets — widgets that auto-initialise on every page load can open a new connection on each navigation without cleaning up the old one.
  • Missing visibilitychange cleanup — custom scripts that don't close their push connection when the tab is hidden or unloaded will leave orphan sockets behind.

How to identify a reconnection loop

  1. Open your browser's developer tools and go to the Network tab.
  2. Filter by push.
  3. Look for repeated requests to /rest/push?pushRef=... — healthy behaviour is one long-lived request per tab. Many short-lived requests indicate a loop.
  4. Check the pushRef values. If they all share the same ID, the same tab is reconnecting repeatedly (usually a proxy timeout or network issue). If each request has a different pushRef, something is re-initialising the client — usually an embedded widget or a custom script.

How to resolve reconnection loops

If the loop is on a single tab

  • Close and reopen the tab to reset the connection.
  • Check that your network or VPN isn't terminating idle connections aggressively.
  • If you're behind a corporate proxy, confirm it allows long-lived SSE or WebSocket connections.

If the loop is caused by an embedded widget

  • Ensure the widget is only initialised once per page, not on every route change.
  • Add a cleanup handler on visibilitychange and beforeunload to close the connection gracefully.
  • Avoid embedding the n8n editor inside SPAs that re-mount the iframe on navigation.

If the loop is caused by a custom script

  • Confirm the script doesn't open its own /rest/push connection — only the editor should.
  • Make sure any polling logic respects the existing push channel rather than competing with it.

Server-side mitigations we have in place

On Awesomate's infrastructure, we already apply the following protections so you don't have to think about them:

  • Stale entry sweeping — we periodically remove entries from the pushRef map based on last heartbeat, so dead sockets don't accumulate.
  • Shortened heartbeat interval — we detect dead sockets sooner, preventing zombie connections.
  • One live connection per pushRef — if a duplicate connection opens for the same pushRef, the older one is closed.
  • Non-blocking push handler — the push handler is kept off any synchronous or blocking work paths so it remains responsive under load.

When to contact support

If you've ruled out the client-side causes above and you're still seeing reconnection loops, raise a ticket with:

  • A HAR export of the Network tab showing the repeated /rest/push requests.
  • The approximate time the loop started.
  • Whether the affected tab is the standard editor, an embedded iframe, or a custom integration.

This gives us enough information to correlate with server logs and pinpoint whether the issue is upstream of n8n or inside your client setup.