Fix 3 Incorrect Queue Type Errors in n8n Queue Mode

n8n Queue Mode Errors / Leave a Comment
Step by Step Guide to solve n8n queue mode incorrect queue type
Step by Step Guide to solve n8n queue mode incorrect queue type

Who this is for: n8n administrators and developers troubleshooting queue‑backend mismatches in production or self‑hosted deployments. We cover this in detail in the n8n Queue Mode Errors Guide.

Quick Diagnosis

Symptom Typical cause One‑line fix
Error: Incorrect queue type appears in the n8n UI or logs Queue backend does not match the selected Queue Mode (e.g., BullMQ selected but only Bull is installed) Set QUEUE_TYPE to the exact backend name (bull or bullmq) and restart n8n.

TL;DR – Install the correct queue library (npm i bull or npm i @taskforces/bullmq), set QUEUE_TYPE accordingly, and restart the service. The error disappears.

1. Why “Incorrect queue type” Happens ?

If you encounter any n8n queue mode incorrect queue name resolve them before continuing with the setup.

Queue backend overview

Backend npm package Core trait
Bull bull Simple API, Redis‑only, good for low‑to‑medium throughput
BullMQ @taskforces/bullmq (or bullmq) Modular, event‑rich, better scaling, Redis ≥ 5.0
Other Community packages (Bee‑Queue, Kue) Varying APIs, often less maintained

When QUEUE_MODE=queue, n8n expects QUEUE_TYPE to match the installed library. A mismatch triggers the Incorrect queue type error.

EEFA note – Pin the exact queue‑library version in package.json and lock Redis to ≥ 5.0 for BullMQ. Mismatched versions can cause race‑conditions that surface as this error under load.

2. Selecting the Right Queue Backend

Decision checklist

Requirement Recommended backend
< 500 jobs/s, simple retries Bull
> 500 jobs/s or need per‑job progress events BullMQ
Must run on Redis Cluster (≥ 6.0) BullMQ
Legacy Bee‑Queue APIs Keep Bee‑Queue only if migration isn’t possible
Need strict FIFO with minimal latency BullMQ (priority & rate‑limiting)

EEFA warning – Never mix Bull and BullMQ in the same Redis DB; purge the queue when switching backends.

3. Step‑by‑Step Configuration

3.1. Using Bull (simplest)

Install

npm install bull@4.10.0   # exact version for stability

Docker‑compose environment

environment:
  - QUEUE_MODE=queue
  - QUEUE_TYPE=bull          # must match the npm package name
  - REDIS_HOST=redis
  - REDIS_PORT=6379

Restart

docker compose restart n8n

Verify – tail logs for confirmation

docker logs -f n8n | grep "Queue type"
# Expected output: "Queue type set to bull"

3.2. Using BullMQ (high‑scale)

Install

npm install @taskforces/bullmq@2.0.0   # or `bullmq` if you prefer upstream

Docker‑compose environment

environment:
  - QUEUE_MODE=queue
  - QUEUE_TYPE=bullmq
  - REDIS_HOST=redis
  - REDIS_PORT=6379
  - REDIS_TLS=false          # set true if TLS‑terminated Redis

Optional – enable job events

environment:
  - BULLMQ_ENABLE_EVENTS=true

Restart & verify

docker compose restart n8n
docker logs n8n | grep "Queue type"
# Should output: "Queue type set to bullmq"

3.3. Switching Backends (Bull ↔ BullMQ)

Step Action
1 Stop n8n: docker compose stop n8n
2 Purge the old queue (run once):

const Bull = require('bull');
const q = new Bull('n8n', { redis: { host: process.env.REDIS_HOST } });
await q.obliterate({ force: true });
3 Uninstall the previous package (npm uninstall bull or npm uninstall @taskforces/bullmq).
4 Install the new package (see 3.1 or 3.2).
5 Update QUEUE_TYPE env var.
6 Start n8n and monitor logs.

EEFA tip – Perform the purge on a non‑production replica or during a maintenance window to avoid losing in‑flight jobs.

4. Advanced Troubleshooting

Common symptom matrix

Symptom Likely cause Diagnostic command Fix
`Incorrect queue type` after restart Both bull **and** bullmq present in node_modules npm ls bull bullmq Uninstall the unwanted package (npm uninstall bullmq if you need Bull).
Same error but logs show QUEUE_TYPE=bull Env var not propagated (Docker secret mis‑named) docker exec n8n printenv | grep QUEUE_TYPE Correct the variable name; rebuild the container if using a .env file.
No error, but jobs never run Worker container still uses old lib Inspect worker env vars and package.json Align all worker containers to the same QUEUE_TYPE.
“Job stalled” warnings in BullMQ logs Redis maxmemory-policy set to noeviction causing OOM redis-cli CONFIG GET maxmemory-policy Switch to allkeys-lru or increase Redis memory.

EEFA – In clustered Redis environments, ensure every node shares the same QUEUE_TYPE. A single node running Bull while others run BullMQ will corrupt the shared job set. If you encounter any n8n queue mode incorrect priority resolve them before continuing with the setup.

5. Code Samples: Direct Queue Interaction (custom nodes)

5.1. Enqueue a job with Bull

Create the queue client

const Bull = require('bull');

const n8nQueue = new Bull('n8n', {
  redis: { host: process.env.REDIS_HOST, port: process.env.REDIS_PORT },
});

Add a job

module.exports = async function addJob(data) {
  const job = await n8nQueue.add('workflow', data, {
    attempts: 3,
    backoff: { type: 'exponential', delay: 5000 },
  });
  return job.id;
};

5.2. Enqueue a job with BullMQ

Create the queue client

const { Queue } = require('@taskforces/bullmq');

const n8nQueue = new Queue('n8n', {
  connection: {
    host: process.env.REDIS_HOST,
    port: process.env.REDIS_PORT,
  },
});

Add a job

module.exports = async function addJob(data) {
  const job = await n8nQueue.add('workflow', data, {
    attempts: 3,
    backoff: { type: 'exponential', delay: 5000 },
  });
  return job.id;
};

EEFA note – BullMQ’s Job object includes a queueName property; Bull returns only id. Adjust downstream handling accordingly.

7. Frequently Asked Questions (FAQ)

  • Q1. Can I use BullMQ with a Redis Cluster?
    Yes. Set REDIS_CLUSTER=true and provide an array of node addresses; BullMQ natively supports clusters (Redis ≥ 6.0).
  • Q2. Do I need to change workflow definitions when switching backends?
    No. n8n’s job payload format is backend‑agnostic; only the queue client code changes.
  • Q3. Is there a performance penalty using Bull instead of BullMQ?
    Bull can be marginally faster for tiny payloads (< 1 KB) but scales poorly beyond ~1 k jobs/s. For most production workloads BullMQ is the safer bet.
  • Q4. How do I monitor queue health?
    • Bull: npm i bull-board → mount at /admin/queues.
    • BullMQ: npm i @taskforces/bullmq-ui → similar UI.

    Both expose metrics (waiting, active, completed, failed) that can be scraped by Prometheus.

Conclusion

The “Incorrect queue type” error is a straightforward mismatch between the QUEUE_TYPE environment variable and the queue library actually installed. By installing the correct package (Bull or BullMQ), aligning QUEUE_TYPE, and, when necessary, purging old queue data, you restore n8n’s queue processing instantly. This fix eliminates the error, ensures reliable job execution, and keeps your production workflow stable.

Prepared by the senior SEO & technical strategy team – authoritative, production‑ready guidance.

Must Read

Leave a Comment

Your email address will not be published. Required fields are marked *