QueueScope

Articles & guides

Why is a BullMQ job stuck in waiting-children?

A parent in waiting-children may be doing exactly what its flow requires: waiting for dependent work. Investigate the child jobs before treating the parent as a failed processor.

Separate waiting from failure

In a typical BullMQ flow, a parent becomes eligible to run after its child jobs complete successfully. A child can belong to another queue, so looking only at the parent queue can miss the job holding up the workflow. Failure-handling options can change how a parent responds to a failed child; check the options used when your flow was created.

Open the dependency graph

In QueueScope, inspect the parent and choose View parent and child jobs. You can also enter its job ID in Flow graph. The graph shows ancestors and descendants across queues. Select a node to inspect its payload, state, options, failure reason, and timestamps.

QueueScope offline demo flow with a parent waiting on a failed child

Investigate the child’s current state

The graph is a view of retained job data. It cannot replace worker logs or establish that a named worker connection is processing this specific job.

Handle a partial graph

QueueScope limits a graph to 80 jobs, eight ancestor levels, and six descendant levels. A partial-graph notice means the displayed branch is incomplete. Open a descendant’s flow to explore that branch instead of assuming the visible nodes represent every dependency.

Jobs under another prefix can be inspected, but their mutations are disabled. Connect to the intended prefix before considering a job action. Start with a read-only profile while you establish the relationship.

Verify the whole workflow after a fix

If an eligible child needs a retry, fix its cause and confirm that repeating it is appropriate. Then watch the child’s result and refresh the parent’s state. A retry request being accepted is not evidence that the whole workflow completed.

For the underlying semantics and available failure options, read the official BullMQ flow documentation. For error investigation, follow the failed-job guide.