Skip to content

fix: dispatch must not report busy after a synchronous failure - #6180

Merged
mcollina merged 3 commits into
nodejs:mainfrom
RegretSSS:fix/issue-6054
Nov 17, 2026
Merged

mcollina merged 3 commits into
nodejs:mainfrom
RegretSSS:fix/issue-6054

Conversation

@RegretSSS

Copy link
Copy Markdown
Contributor

Fixes #6054

Root cause

When a request fails synchronously during dispatch (e.g. an invalid header value like \n raises InvalidArgumentError in lib/core/request.js before anything is queued), DispatcherBase.dispatch() (lib/dispatcher/dispatcher-base.js) catches the error, delivers it via handler.onResponseError(), and then returns false.

But per undici's contract, dispatch() returning false means "the request was accepted and the dispatcher is saturated — a drain event will follow". Neither holds for a synchronous failure: nothing was queued, no capacity was consumed, and no drain will ever arrive.

PoolBase trusts that contract (lib/dispatcher/pool-base.js): it marks the idle client kNeedDrain = true. With running: 0 there is no in-flight request whose completion could trigger a drain, kGetDispatcher skips need-drain clients, and connections: 1 prevents creating a new one — every subsequent valid request queues forever. With a finite connections: N, N validation failures exhaust all slots.

Fix

lib/dispatcher/dispatcher-base.js — the catch path now returns true:

       handler.onResponseError(null, err)
-      return false
+      return true

This is fixed at the owner of the return-value contract rather than patching each consumer, so PoolBase (kDispatch, the kOnDrain drain loop, kDrainQueue) and Agent's pass-through all benefit at once. Real saturation is still reported honestly by the normal path in Client[kDispatch], so capacity semantics are unchanged.

Open question for maintainers (happy to adjust): for a closed/destroyed dispatcher whose dispatch fails synchronously, this returns true unconditionally; an alternative is return !this[kClosed] && !this[kDestroyed] (as in #6055). I believe the unconditional form is safer for PoolBase because a false there would again mark a client as waiting for a drain that never comes — pool lifecycle already removes closed clients — but I'd like a maintainer's take on that edge.

Tests

  • Two regression tests added to test/pool.js:
    1. the reporter's scenario (pool stays usable after a request validation error),
    2. a queued-request variant covering the kOnDrain drain-loop path.
  • Verified both tests fail without the fix (2 fail / 0 pass, 1s watchdog) and pass with it.
  • node --test test/{pool,client,dispatcher}.js: 109 tests — 108 pass / 0 fail / 1 env-skip.
  • Full unit suite: 1690 tests — 1685 pass / 0 fail / 5 env-skips.
  • eslint clean on touched files.

Note on prior attempts

#6055 (same-file approach, stalled since Oct 20) and #6081 (pool-side mitigation, now conflicting with main) both appear inactive; this PR revives the fix from the dispatcher-contract layer with the edge-case question called out above.

Disclosure

我在测试自研 Agentloop 的工作情况,选中此 Issue 为测试目标,已过验证。
(For clarity: this fix was produced by my own agent-loop implementation and has been verified as described above.)

DispatcherBase.dispatch catches synchronous request validation errors
(e.g. an invalid header throwing UND_ERR_INVALID_ARG from the Request
constructor) and, after delivering them through onResponseError,
returned false. By convention a false return means the dispatcher has
queued the request internally and is saturated: a 'drain' event will
be emitted once it has capacity again.

But a synchronously rejected request was never queued, consumed no
capacity, and can never trigger a drain. PoolBase trusted the false
return and permanently marked the idle client as needing drain
(kNeedDrain), so with limited connections the client slot was never
returned to rotation and every subsequent request waited in the pool
queue forever with nothing running and no event left to resume it
(nodejs#6054).

Return true instead: the dispatcher did not take ownership of the
request and remains available. This fixes all three PoolBase call
sites (kDispatch, kOnDrain, kDrainQueue) and Agent at once, at the
layer that owns the dispatch contract.
Regression tests for nodejs#6054, adapted from the reporter's
reproduction and following the existing test/pool.js conventions:

- a synchronously rejected request (invalid header) must not take the
  idle client out of rotation: the pool keeps serving requests with
  connections: 1 and the client slot is not consumed
- a queued request that fails validation when the pool drains its
  queue must not end the drain loop or mark the just-drained client
  busy, leaving later queued requests stuck

Replaces test/issue-6054-repro.js, whose scenario is now covered here.

@mcollina mcollina left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.68%. Comparing base (5ab61dd) to head (aa31568).

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #6180      +/-   ##
==========================================
- Coverage   91.68%   91.68%   -0.01%     
==========================================
  Files         113      113              
  Lines       44449    44454       +5     
==========================================
+ Hits        40752    40756       +4     
- Misses       3697     3698       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@mcollina
mcollina merged commit e2d3523 into nodejs:main Nov 17, 2026
38 checks passed
@github-actions github-actions Bot mentioned this pull request Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Pool permanently stalls after synchronous request validation errors

4 participants