[Bug]: APIRequestContext ignores the server's Keep-Alive timeout, producing ECONNRESET on socket reuse

[nick-vogel]

Version

1.58.2

Steps to reproduce

playwright-core/lib/server/utils/happyEyeballs.js creates a module-level singleton http.Agent({ keepAlive: true }), shared by every request context in a worker. Node's agent does not parse the response's Keep-Alive: timeout=N header, so it will hold and reuse a socket the server has already committed to closing. The reuse is answered with a RST, which surfaces as apiRequestContext.<verb>: read ECONNRESET or socket hang up.

Reproduced against a Next.js 16 dev server, which is Node's HTTP server with the default keepAliveTimeout of 5s. It advertises the value on every response (Keep-Alive: timeout=5), and a raw socket idled against it is closed at 6.06s.

I swept request timings across that boundary:

• idle server: 0 failures in 228 requests
• same sweep, six concurrent readers: 2 failures in 87, both landing exactly at the 6000ms mark

The server was three hours old and 154 MB resident for both sweeps, so this is not memory pressure or server degradation. Concurrency widens the window between the client's decision to reuse a pooled socket and the write reaching the server; it is not itself the cause.

Expected behavior

A pooled socket is not reused after the server's advertised Keep-Alive: timeout has elapsed, so an idempotent request does not fail with ECONNRESET.

Actual behavior

The request throws read ECONNRESET.

What makes this hard to attribute: Chromium's network stack resends a request that failed on a socket it had reused, so page navigations never show this. Only APIRequestContext calls do. In a suite that mixes both, the failures cluster in whichever specs happen to use the request context, which reads as a bug in those specs rather than as a transport fault. It took a packet-level repro to see otherwise.

The consequence in our case was worse than a flaky test. A dropped cleanup PATCH at the end of a spec left fixture data in a shared database, and because our seed only creates what is absent, that state persisted and poisoned later runs.

Suggested fixes, in preference order

1. Honour the Keep-Alive: timeout header when deciding whether a pooled socket is still usable.
2. Default maxRetries above 0 for idempotent verbs.
3. Document the hazard on APIRequestContext. maxRetries defaults to 0 and nothing in the docs points a user toward it for this failure.

Workaround

Wrap the request context so every idempotent verb carries maxRetries. That is narrow and safe: fetch.js retries only when e.code === 'ECONNRESET' and a status code never reaches that catch, so no real server failure is masked. We deliberately excluded POST, since the reset is raised on the read side and the server may already have processed the create, making a replay a duplicate row.

Setting Connection: close via use.extraHTTPHeaders also fixes it completely (0 failures in 87 under the load that gave 2), but Chromium forwards the header, so the browser loses keep-alive for every navigation and every asset to fix a fault that only ever touched the API context.

Environment

• Playwright 1.58.2
• Node v26.3.0
• macOS (Darwin 25.4.0), arm64
• Server under test: Next.js 16.2.11 dev server

[AbishekCoder1]

I tried to reproduce this against a real Next.js dev server before commenting, since the ECONNRESET/Keep-Alive interaction can be timing-sensitive.

Setup

• Fresh create-next-app (Next.js 16.3.5), npm run dev
• Confirmed the server advertises Keep-Alive: timeout=5 on every response, matching what's described here
• Client: plain http.Agent({ keepAlive: true }), no proxy, hitting localhost directly
• macOS (arm64)

Method
6 concurrent readers per cycle, warming up the socket pool, then an idle gap randomized to straddle the 5s advertised timeout (4.8s–5.2s), then 6 more concurrent readers fired at once — repeated for 15 cycles (90 total second-wave requests per run).

Result

Node	Runs	ECONNRESET
v24.19.0	2	0/90, 0/90
v26.3.0	1	0/90

Also ran the same methodology against a bare http.createServer with keepAliveTimeout = 1000 (shorter timeout, same idea) — also 0/90 across two runs.

I don't doubt the original packet-level sweep — just flagging that I couldn't reproduce it with this approach on my setup. Could be something specific to the original environment (OS/network stack, a particular interface, background load affecting the timing window) that I'm not hitting. Happy to share the reproduction script if it's useful for narrowing down the difference, or to try again with different conditions if there's a detail I'm missing.

[github-actions]

Hi, I'm the Playwright bot and I took a first look at this on macOS (arm64, macOS 26.6, Node v24.20.0).

I couldn't reproduce it, and the premise doesn't hold on modern Node. Node's http.Agent does parse Keep-Alive: timeout=N and evicts the pooled socket when it elapses, and Node's client additionally retries a request that fails with ECONNRESET on a socket it had reused. I measured both, against tip-of-tree (1.64.0-alpha-2026-09-14, sha 52a0e72) and against the version you reported, 1.58.2.

Two things worth knowing about the source you cited:

• packages/playwright-core/src/server/utils/happyEyeballs.ts no longer holds the agent. On tip-of-tree each APIRequestContext owns its own agent per protocol (fetch.ts, _ensureAgent), destroyed with the context — so the worker-wide singleton is gone regardless of this bug.
• keepAlive: true is still there, and Playwright doesn't parse the header itself — it doesn't need to, Node does it underneath.

What I ran (all on macOS, Node v24.20.0)

Socket counting against a real Node server (server.keepAliveTimeout = 60000 so the server never closes first — only the advertised hint can end the reuse):

Client	Keep-Alive: timeout=1 advertised	Idle	TCP connections
Playwright ToT	yes	2000ms	2 — not reused
Playwright 1.58.2	yes	2000ms	2 — not reused
plain http.Agent({keepAlive:true})	yes	2000ms	2 — not reused
plain http.Agent({keepAlive:true})	no	2000ms	1 — reused
Playwright ToT	no	0 / 600 / 2000 / 6000ms	1 — reused

So reuse past the advertised timeout doesn't happen; drop the header and reuse comes back. That's Node honouring the hint, not us.

Failure sweeps, all 0 failures:

• Boundary sweep, ToT and 1.58.2: keepAliveTimeout = 500, gaps of 480/490/495/498/499/500/501/502/505/510/520ms, 6 requests each — 0/66 failed on both versions.
• Your concurrency shape, ToT: 6 concurrent readers, idle randomized across the 1s boundary, 6 more fired at once, 15 cycles — 0/90 failed.
• Server that resetAndDestroy()s an idle socket without advertising anything: 0/10.
• Server that RSTs the reused request after it's been written — i.e. the client deliberately losing the race it can't win — 0/5 with the default maxRetries: 0, and 0/5 with maxRetries: 2. Node recovered on its own; the error never reached APIRequestContext.

That last one is the interesting one: even when I force the exact packet sequence you describe, Node's own retry-on-reused-socket swallows it.

Which lines up with Abishek N (@AbishekCoder1)'s non-repro above, on both Node v24 and v26.

That doesn't make your packet capture wrong — an RST answering a reuse is a real thing to see on the wire — but something in your setup is getting past Node's two layers of protection, and that's the part I can't guess. The most useful thing would be a self-contained repro: a tiny http.createServer with keepAliveTimeout set and the request loop that fails, no Next.js. Failing that, does the response from your Next.js dev server actually carry Keep-Alive: timeout=5 on the specific request that failed (curl -sv the same route), or only on some of them? A proxy, tunnel, or VPN between client and server would also explain it — was anything like that in the path?

I'm a first pass here, so treat this as "couldn't reproduce with the information available", not a dismissal.

_{Triaged on macOS by the Playwright bot - agent run}

[nick-vogel]

Thanks for looking. I can now reproduce the premise deterministically, with no Next.js, no proxy, no load and no timing window. There are two scripts below: the first shows the advertised timeout being ignored, the second shows the error that's thrown.

_http_agent.js, keepSocketAlive():

let agentTimeout = this.options.timeout || 0;
...
if (hint) {
  let serverHintTimeout = (NumberParseInt(hint) * 1000) - this.agentKeepAliveTimeoutBuffer;
  serverHintTimeout = serverHintTimeout > 0 ? serverHintTimeout : 0;
  if (serverHintTimeout === 0) {
    canKeepSocketAlive = false;          // (a)
  } else if (serverHintTimeout < agentTimeout) {
    agentTimeout = serverHintTimeout;    // (b)
  }
}

Playwright builds new http.Agent({ keepAlive: true }) with no timeout, both in happyEyeballs.ts on 1.58.2 and in fetch.ts _ensureAgent() on main. So agentTimeout is 0, no positive serverHintTimeout is ever less than 0, branch (b) never runs, and the socket is given setTimeout(0), which means never. The advertised value is parsed and then discarded.

node keepalive-hint.mjs

server advertises Keep-Alive: timeout=5 and never closes a socket itself

{ keepAlive: true }                    REUSED after 15s idle
{ keepAlive: true, timeout: 60000 }    new socket

Identical on v20.10.0, v24.21.0 and v26.3.0. A socket the server said to drop at 5s is still reused at 15s.

// keepalive-hint.mjs
import http from 'node:http'

const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
const ADVERTISED = 5
const IDLE_MS = 15_000

let opened = 0
const server = http.createServer((req, res) => {
  res.writeHead(200, {
    'content-length': 2,
    connection: 'keep-alive',
    'keep-alive': `timeout=${ADVERTISED}`,
  })
  res.end('ok')
})
// The server never closes a socket itself, so only the hint can end the reuse.
server.keepAliveTimeout = 600_000
server.headersTimeout = 660_000
server.on('connection', () => { opened += 1 })
const origin = await new Promise((r) =>
  server.listen(0, '127.0.0.1', () => r(`http://127.0.0.1:${server.address().port}`)))

const get = (agent) => new Promise((resolve, reject) => {
  const req = http.get(`${origin}/x`, { agent }, (res) => { res.resume(); res.on('end', resolve) })
  req.on('error', reject)
})

async function check(label, agent) {
  await get(agent)
  const before = opened
  await sleep(IDLE_MS)
  await get(agent)
  console.log(`${label.padEnd(38)} ${opened === before ? 'REUSED after 15s idle' : 'new socket'}`)
  agent.destroy()
}

console.log(`server advertises Keep-Alive: timeout=${ADVERTISED}, node ${process.version}\n`)
await check('{ keepAlive: true }', new http.Agent({ keepAlive: true }))
await check('{ keepAlive: true, timeout: 60000 }', new http.Agent({ keepAlive: true, timeout: 60_000 }))
server.close()

Every measurement in the triage table advertised Keep-Alive: timeout=1, and the boundary sweep used keepAliveTimeout = 500. Both land in branch (a): 1000 - 1000 = 0, so canKeepSocketAlive is false and the socket is never pooled at all. I measured that separately, against a server that never closes anything: at timeout=1 a new socket is opened at every gap, including a gap of 0ms. So the "2 connections, not reused" row is not the hint being honoured, it is keep-alive being off entirely, and a sweep run in that state cannot reach the bug at any gap. At timeout=2, 3, 4 and 5 the socket is reused well past the advertised value.

A raw TCP server answers request 1 and advertises timeout=5, holds the socket open through a 6s idle gap, and then answers request 2 on that reused socket with RST instead of a response. That is the packet sequence from the original capture, chosen rather than raced for. The client only gets that far because it kept a socket it was told to drop.

node reset-on-reuse.mjs

plain http.Agent                 request 2 THREW ECONNRESET (reusedSocket=true), so node did NOT retry it
APIRequestContext maxRetries=0   request 2 THREW apiRequestContext.get: read ECONNRESET
APIRequestContext maxRetries=3   request 2 SUCCEEDED (200)

Identical on all three Node versions. The retry claim states Node sets req.reusedSocket precisely so that a caller can decide to retry, and does not retry on its own. The plain-agent line above is that is measured. Chromium does resend, which is why navigations never show this and only apiRequestContext does.

// reset-on-reuse.mjs
import net from 'node:net'
import http from 'node:http'
import path from 'node:path'
import { createRequire } from 'node:module'

const requireFromCwd = createRequire(path.join(process.cwd(), 'noop.js'))
const sleep = (ms) => new Promise((r) => setTimeout(r, ms))

const ADVERTISED = 5
const IDLE_MS = 6000
const BODY = '{"ok":true}'
const RESPONSE =
  'HTTP/1.1 200 OK\r\n' +
  `content-length: ${BODY.length}\r\n` +
  'connection: keep-alive\r\n' +
  `keep-alive: timeout=${ADVERTISED}\r\n\r\n` +
  BODY

const server = net.createServer((socket) => {
  let served = 0
  socket.on('error', () => {})
  socket.on('data', () => {
    served += 1
    // Answer the first request; RST the reused socket at the second.
    if (served === 1) socket.write(RESPONSE)
    else socket.resetAndDestroy()
  })
})
const origin = await new Promise((r) =>
  server.listen(0, '127.0.0.1', () => r(`http://127.0.0.1:${server.address().port}`)))

const agent = new http.Agent({ keepAlive: true })
const nodeGet = () => new Promise((resolve, reject) => {
  const req = http.get(`${origin}/x`, { agent }, (res) => {
    res.resume()
    res.on('end', () => resolve({ reusedSocket: req.reusedSocket }))
  })
  req.on('error', (error) => reject(Object.assign(error, { reusedSocket: req.reusedSocket })))
})

await nodeGet()
await sleep(IDLE_MS)
try {
  const { reusedSocket } = await nodeGet()
  console.log(`plain http.Agent                 request 2 SUCCEEDED (reusedSocket=${reusedSocket})`)
} catch (error) {
  console.log(`plain http.Agent                 request 2 THREW ${error.code} (reusedSocket=${error.reusedSocket}), so node did NOT retry it`)
}
agent.destroy()

const { request } = requireFromCwd('@playwright/test')

async function throughPlaywright(maxRetries) {
  const context = await request.newContext({ baseURL: origin })
  await context.get('/x', { maxRetries })
  await sleep(IDLE_MS)
  let outcome
  try {
    outcome = `SUCCEEDED (${(await context.get('/x', { maxRetries })).status()})`
  } catch (error) {
    outcome = `THREW ${String(error.message).split('\n')[0]}`
  }
  await context.dispose()
  console.log(`APIRequestContext maxRetries=${maxRetries}   request 2 ${outcome}`)
}

await throughPlaywright(0)
await throughPlaywright(3)
server.close()
process.exit(0)

Suggested fix

Give the agent a timeout, so that branch (b) can run and the advertised value is honoured. In fetch.ts _ensureAgent() on main:

agent = protocol === 'https:'
  ? new https.Agent({ keepAlive: true, timeout: 60_000 })
  : new http.Agent({ keepAlive: true, timeout: 60_000 })

Any value larger than a realistic advertised hint works, since the hint wins when it is smaller. That leaves maxRetries as it is, and it does not depend on the per-context agent change already on main.

[mohanram-dev]

I've verified the root cause where Node's http.Agent discards the server's Keep-Alive: timeout hint when options.timeout is omitted, and submitted a fix with regression test coverage in #42720.