Overview
This node acts as a trigger for BullMQ queues, allowing workflows to register workers that listen for jobs on specified queues. When a job is received, the node processes it according to configured options and can respond immediately or defer response handling based on user settings.
Common scenarios include:
- Automating workflow execution triggered by jobs added to BullMQ queues.
- Integrating external job processing systems with n8n workflows.
- Handling asynchronous job results with flexible response strategies.
For example, you might use this node to start a workflow whenever a new job is added to a queue named "emailQueue" to send emails asynchronously.
Properties
| Name | Meaning |
|---|---|
| Queue Source | Selects the source of the queue: either predefined "Workflows" or a "Custom" queue name. |
| Queue Name | The name of the queue to listen to for incoming jobs (required if "Custom" queue source chosen). |
| Job Name | The specific job name to listen for within the queue (required). |
| Respond Type | Defines how the node responds when a job is received: |
| - Use Last Node: Waits for the last node in the workflow to complete before responding. | |
| - Immediate: Responds immediately upon receiving the job without waiting. | |
| - Use Respond Node: Uses a dedicated respond node to handle the response. | |
| Options | Collection of additional settings: |
| - Lock Duration | Duration in milliseconds to hold the lock on the job during processing (default 60000 ms). |
| - Concurrency | Number of jobs that can be processed concurrently (default 1). |
| - Run Retry Delay | Time in milliseconds to wait before retrying a failed job (default 5000 ms). |
| - Only Data | Whether to return only the job's data or the full job object (default true). |
Output
The node outputs JSON data representing the job received from the BullMQ queue. Depending on the "Only Data" option, this output can be either:
- The raw job data payload (if
onlyDatais true). - The full job object serialized to JSON (if
onlyDatais false).
If binary data were involved, it would typically represent job-related files or attachments, but this node focuses on JSON job data.
Dependencies
- Requires a Redis server connection since BullMQ depends on Redis for queue management.
- Needs an API key credential or equivalent Redis authentication configured in n8n credentials.
- Uses the BullMQ library internally to create workers and process jobs.
- Relies on n8n's workflow context and helper methods for deferred promises and job locking.
Troubleshooting
- Queue Name Missing: If no queue name is provided (and custom source is selected), the node throws an error. Ensure the queue name is set.
- Token Missing Error: Indicates that a required lock token was not received or lost during job processing. This usually means the job lock expired or was not acquired properly.
- Job Waiting Error: If the job status is "waiting," the node throws a delayed error indicating the job is not ready for processing yet.
- Missing Execution Data: Errors about missing last executed node or run data suggest workflow execution did not complete as expected; check workflow design.
- Connection Issues: Failures connecting to Redis will prevent the node from working. Verify Redis credentials and network connectivity.
- Concurrency Misconfiguration: Setting concurrency too high may overload Redis or cause unexpected behavior; tune according to your environment.
Links and References
- BullMQ GitHub Repository – Official BullMQ library used by this node.
- Redis Documentation – For setting up and managing Redis servers.
- n8n Documentation – General information on creating and using nodes in n8n workflows.