n8n Worker in Queue Mode Ignores Custom Port Environment Variable

Below is an explanation of what's happening and how to resolve it.

What’s Happening

When you launch a worker alongside the main instance in queue mode, the worker process starts in “main” mode internally. This means that—even though its primary job is to pick up and execute queued workflows—it still runs a server that (optionally) exposes endpoints (like health checks or metrics) on the default port (usually 5678). The worker therefore ignores any environment variable you set for a “different port” because it isn’t designed to reconfigure its listening port through those variables.

The error you’re seeing (typically an “address in use” error) occurs because both the main process and the worker are trying to bind to the same default port on the same machine.

How to Fix This

There are a couple of options you can employ:

1. Use a Different Port via Container Port Mapping (when using Docker):
   If you run n8n using Docker, you can remap the port for the worker container. For example, if the worker internally listens on port 5678, you can start it with a different external port:

   BASHCopied
   docker run --name n8n-queue -p 5679:5678 docker.n8n.io/n8nio/n8n worker

   This way, the worker’s internal port remains 5678 while the machine uses port 5679 for external access (if needed).

2. Separate the Processes Across Machines:
   When running on the same machine, both processes share the same network namespace. By hosting the worker on a different machine, you avoid port conflicts entirely.

3. Disable Unnecessary Endpoints in the Worker:
   If you don’t require features like health checks from the worker’s server (which does not impact its role in queue mode), you might consider disabling the endpoints. (Refer to the n8n documentation on disabling webhook processing in the main process.) That said, worker processes by design will bind to the default port for optional endpoints unless an alternative mechanism is provided.

In Summary

The worker in queue mode isn’t designed to change its default listening port through an environment variable. As a result, if you run both main and worker on the same host without adjusting your setup, they’ll conflict over the port. The recommended approaches are to use container-level port mapping or to deploy the worker on a different host, thereby avoiding the conflict.

This behavior is expected given the current design and configuration methods available in n8n queue mode.