Who this is for: n8n administrators and developers who use Queue Mode in production and need deterministic job ordering. We cover this in detail in the n8n Queue Mode Errors Guide.
Quick Diagnosis
High‑priority jobs are being skipped while lower‑priority jobs run. The root cause is a mis‑configured priority field in the queue‑mode payload or an overriding N8N_QUEUE_PRIORITY environment variable. Fix the numeric priority ( 0 = highest, larger = lower ) before the job is enqueued, then restart the affected workers.
Immediate Fixes
If you encounter any n8n queue mode incorrect queue name resolve them before continuing with the setup.
| Symptom | Fix |
|---|---|
| High‑priority job never runs | 1️⃣ Ensure the payload contains priority: 0 (or the numeric value you defined as “high”).2️⃣ Verify the worker’s N8N_QUEUE_PRIORITY env var isn’t overriding the payload.3️⃣ Restart the worker process. |
| Low‑priority jobs run before high‑priority ones | Apply the same steps; also confirm no global defaultPriority is set to a low value. |
1. How n8n Queue Mode Handles Priority ?
BullMQ stores each job with a numeric priority property:
| Value | Meaning |
|---|---|
| 0 | Highest priority (processed first) |
| 1, 2, … | Lower priorities (higher numbers = lower priority) |
When a worker pulls jobs, BullMQ sorts by priority first, then by timestamp. A missing or malformed priority can be coerced to Infinity, making the job the *lowest* priority.
EEFA note: In production clusters, a single mis‑typed priority can starve critical workflows for minutes, breaching SLAs.
2. Common Causes of Incorrect Priority Assignment
| Cause | Why it Happens | Typical Symptom |
|---|---|---|
Payload uses a string ("high" instead of 0) |
BullMQ expects a number; a string becomes NaN → lowest priority. |
High‑priority jobs sit at the end of the queue. |
Environment variable overrides (N8N_QUEUE_PRIORITY=5) |
Worker forces every job to that priority, ignoring the payload. | All jobs run at the same low priority. |
Missing priority field |
n8n falls back to the worker’s defaultPriority (often 10). |
No job ever gets priority 0 unless explicitly set. |
Custom node rewrites priority |
Node’s execute() returns { priority: "high" }. |
Priority is silently downgraded. |
| Version mismatch (BullMQ < 4.0) | Older BullMQ ignored the priority option in edge cases. |
Inconsistent behavior across workers. |
3. Step‑by‑Step Fix: Correcting Priority Values
3.1 Verify the Payload Structure
{
"workflowId": 42,
"executionId": "c3b9d7e2",
"priority": 0,
"data": { /* … */ }
}
Make sure priority is a **number**; remove any string equivalents.
3.2 Update Custom Nodes (if you have them)
// ❌ Bad – returns a string
return { priority: "high", ...rest };
// ✅ Good – returns a number
return { priority: 0, ...rest };
3.3 Adjust Environment Variables
Edit the worker’s .env (or Docker Compose) file:
# Comment out or delete low‑priority overrides # N8N_QUEUE_PRIORITY=5 N8N_QUEUE_PRIORITY=0 # optional: forces all jobs to high priority
3.4 Restart the Worker
# Systemd sudo systemctl restart n8n-worker # Docker Compose docker compose restart n8n-worker
3.5 Re‑deploy the Affected Workflow
If the stored workflow definition contains a bad priority, update it:
n8n workflow:update --id 42 --set priority=0
3.6 Confirm with a Test Job
Send a high‑priority webhook payload:
curl -X POST http://localhost:5678/webhook/trigger \
-H "Content-Type: application/json" \
-d '{"priority":0,"data":{"msg":"test high priority"}}'
Inspect the Redis queue to verify ordering:
docker exec -it n8n-bullmq redis-cli > ZRANGE n8n:queue:jobs 0 -1 WITHSCORES
The test job should appear at the top with a score reflecting priority 0. If you encounter any n8n queue mode incorrect queue type resolve them before continuing with the setup.
4. Verifying the Fix with Real‑World Tests
| Test | Command | Expected Result |
|---|---|---|
| Single high‑priority job | curl … -d ‘{“priority”:0}’ | Job ID appears first in ZRANGE. |
| Mixed priorities (0, 2, 5) | Enqueue three jobs with those values | Order = 0 → 2 → 5 regardless of timestamps. |
| Worker restart | systemctl restart n8n-worker | Queue order unchanged; no jobs lost. |
| Load test (1 000 jobs, 20 % priority 0) | Run a script that enqueues the mix | High‑priority jobs complete ≈20 % faster than low‑priority ones. |
EEFA tip: Run the load test in a staging environment that mirrors production concurrency. Avoid executing it on a live production queue without a circuit‑breaker, as it can temporarily starve low‑priority jobs.
5. Advanced Troubleshooting & Edge Cases
| Situation | Diagnosis Steps | Fix |
|---|---|---|
| Jobs still ignored after fixing payload | 1. Check worker logs for process.env.N8N_QUEUE_PRIORITY overrides.2. Verify no global defaultPriority is set in config.json. |
Remove/adjust the offending config and restart workers. |
| Multiple workers with different priority settings | Run docker exec … env | grep N8N_QUEUE_PRIORITY on each host. |
Align all workers to the same policy or create a dedicated “high‑priority” pool. |
| BullMQ version < 4.0 | npm list bullmq → version. |
Upgrade to ≥ 4.0 (npm install bullmq@^4). |
| Priority lost after a failed retry | Inspect the job’s attemptsMade and opts.priority fields in Redis. |
Set removeOnFail: false and re‑enqueue with the correct priority. |
Priority ignored when using n8n execute CLI |
CLI defaults to defaultPriority from ~/.n8n/config. |
Pass --priority 0 flag or edit the config file. |
6. Preventive Best Practices
| Practice | Why It Matters |
|---|---|
Validate payloads with a JSON schema (priority must be an integer 0‑10). |
Catches errors before they reach the queue. |
Centralize priority constants (const PRIORITY = { HIGH:0, MEDIUM:5, LOW:10 }). |
Reduces typo risk across nodes. |
| Separate worker pools for critical vs. bulk jobs. | Guarantees high‑priority jobs have dedicated resources. |
Monitor queue health (Grafana + Prometheus metric queue_priority_distribution). |
Early alert when priority distribution skews. |
| Automated tests that enqueue a high‑priority job and assert its position. | CI catches regressions before deployment. |
Conclusion
Ensuring that the priority field is a **numeric value** aligned with worker configuration eliminates the “incorrect priority” error and restores deterministic processing order in n8n’s Queue Mode. Follow the checklist above, verify with the test commands, and lock the fix in with automated validation to keep your workflows running at the intended speed in production.
