Introduction

When async.eachLimit appears to stop after the first item, the problem is almost never the library itself. In nearly every case, the iterator callback is not being called correctly, is being called more than once, or an error is being passed into it and causing the whole loop to end early.

That is the central rule of the async callback style: each item must complete exactly once, and the final callback runs early if any iterator reports an error.

How eachLimit Actually Works

eachLimit(array, limit, iterator, done) runs up to limit iterator calls at the same time. Each iterator receives one item and a callback. The library assumes the item is still in progress until that callback is invoked.

A minimal correct example looks like this:

1const async = require('async');
2
3const values = [1, 2, 3, 4];
4
5async.eachLimit(values, 2, (value, callback) => {
6  setTimeout(() => {
7    console.log('processed', value);
8    callback();
9  }, 100);
10}, (err) => {
11  if (err) {
12    console.error(err);
13    return;
14  }
15
16  console.log('all done');
17});

If callback() is never reached for an item, the loop appears to hang. If callback(err) is called, the loop stops and the final callback receives that error.

The Most Common Failure: Missing Callback

The usual bug is that one branch of the iterator forgets to call the callback:

1async.eachLimit(values, 2, (value, callback) => {
2  if (value === 1) {
3    console.log('first item');
4    return;
5  }
6
7  callback();
8}, (err) => {
9  console.log('done', err);
10});

This looks harmless, but the first item never signals completion. From the library's point of view, the operation is still running forever.

The fix is to make sure every code path reaches the callback:

1async.eachLimit(values, 2, (value, callback) => {
2  if (value === 1) {
3    console.log('first item');
4    callback();
5    return;
6  }
7
8  callback();
9}, (err) => {
10  console.log('done', err);
11});

The Second Common Failure: Error Ends The Loop

eachLimit is fail-fast. If one iterator passes an error, the final callback fires and the loop stops scheduling new work.

1async.eachLimit(values, 2, (value, callback) => {
2  if (value === 1) {
3    callback(new Error('stop here'));
4    return;
5  }
6
7  callback();
8}, (err) => {
9  console.error('ended with', err.message);
10});

That is correct behavior, not a random stop. If you want to keep processing even when some items fail, handle the error inside the iterator and call callback() without passing the error upstream.

Do Not Mix Callback Style And Promise Style Carelessly

Another trap appears when code mixes callback conventions with async or await without understanding which style the function expects. In the classic callback form, you should finish by calling the provided callback. In promise-aware usage, you should return a promise and not manually use the callback at the same time.

If you mix both, you can end up with double completion or with code paths that never complete at all.

Debug The Iterator, Not The Loop

When eachLimit "stops after the first step," add logging around the iterator entry and callback exit. You usually discover that:

• the iterator never calls callback
• an exception prevents the callback from running
• an early return skips the callback
• an error is passed intentionally and terminates the whole flow

That is why the debugging target is the iterator implementation, not the concurrency limit itself.

Common Pitfalls

One common mistake is forgetting to call the iterator callback on one branch of logic. Another is calling it twice, which creates erratic flow-control bugs. Developers also often misread fail-fast error handling as "the loop stopped randomly," when the loop is actually honoring callback(err). Finally, mixing callbacks with promises in the same iterator without a clear ownership model is a reliable way to produce hangs or double-finish behavior.

Summary

• 'async.eachLimit continues only when each iterator calls its callback exactly once.'
• If the iterator never calls the callback, the loop appears stuck.
• If the iterator passes an error, eachLimit stops early by design.
• Debug the iterator code paths, not just the loop declaration.
• Pick one async style per iterator: callback-based or promise-based, not both carelessly mixed.