Flows
Flows let you split a piece of work into a tree of jobs: a parent job waits in the waiting-children state until all of its children have completed, and children can live in other queues and have children of their own. Flows are created with BullMQ's FlowProducer.
The Flows tab of a queue shows these trees as an interactive diagram, so you can see at a glance how far a flow has progressed, which child failed, and what a parent is still waiting for.
INFO
The Flows tab is available for BullMQ and BullMQ Pro queues when the connection supports flows. It isn't shown for Bull (v3) queues, which don't have flows.
Find a flow
The left side of the tab lists the parent jobs in the queue. Each entry shows the job name, its ID, its state as a colored dot, how many children it has and how long ago it was created. Scroll down to load more.
Use the Search flows box at the top of the list to find a specific flow. The diagram for the selected flow opens on the right.
If the queue has no flows yet, the tab tells you so and links to the BullMQ FlowProducer documentation.
Read the diagram
Each job in the tree is a card showing its name, ID, state, when it was created and, once it has run, how long it took. Failed jobs show their error, and active jobs show their progress. Cards are colored by state:
| Color | State |
|---|---|
| Green | Completed |
| Blue | Active |
| Orange | Waiting for children |
| Gray | Waiting |
| Yellow | Delayed |
| Purple | Prioritized |
| Red | Failed |
Use the toolbar buttons to switch between a vertical (top to bottom) and a horizontal (left to right) layout. You can pan and zoom the diagram, and the minimap in the corner shows where you are in large trees.
While any job in the loaded tree is active, the diagram refreshes itself every two seconds, so you can watch a flow complete. Active jobs hidden in a compact child summary don't trigger auto-refresh until their subtree is opened. Use the refresh button in the toolbar to reload the list of flows.
Parents with many children
When a job has more than 10 children, they're grouped into a single summary card instead of being drawn one by one. The summary card shows:
- the total number of children and how many are in each state. Click a state to show only the children in that state, and click it again to clear the filter. Active children represented only in this summary don't trigger auto-refresh until their subtree is opened.
- a search box to filter the children by name.
- a paged list of the children. Click a child to see its details, or click the arrow next to a child's children count to open that child's own subtree.
When you open a subtree, a breadcrumb bar above the diagram shows the path you followed. Click any step to go back up.
Job details and actions
Click any job in the diagram to open its details panel, with its ID, queue, timestamps, and its data, return value, options and stack trace. Use the clipboard buttons to copy the error message or the stack trace.
The panel also has actions for the job, depending on its state:
| Action | Available when the job is |
|---|---|
| Retry | Failed |
| Promote | Delayed |
| Remove | Completed, failed, waiting, waiting for children or delayed |
The diagram reloads after the action, so you can see its effect on the rest of the flow. These actions follow the same role permissions as the Jobs tab.
To see the job in its regular jobs list, click View in Jobs. If the job belongs to a different queue on the same connection, the link takes you to that queue.
Open a flow from the Jobs tab
Jobs that are part of a flow have a View Flow button in the Jobs tab. It opens the Flows tab at the flow's root job, even if the job you started from is deep inside the tree. Large groups of children are shown in summary cards rather than loaded individually. The selected flow is kept in the page URL, so you can share a link to it with your team.