fix: mitigate WSL2 fetch ETIMEDOUTs to Anthropic API (#19) by nujovich · Pull Request #23 · nujovich/mint

nujovich · 2026-05-07T16:25:10Z

Summary

Force IPv4-first DNS resolution at module load to avoid WSL2's NAT routing fetch through an unreachable IPv6 address (root cause of Timeout errors on WSL2 in audit, resolve, and export steps (ETIMEDOUT from fetch to Anthropic API) #19).
Retry callAnthropic up to twice (500ms / 1500ms backoff) on transient network errors only (ETIMEDOUT, ECONNRESET, undici socket/connect errors); HTTP responses are still surfaced as-is.
Add opt-in MINT_DEBUG=1 diagnostics: DNS lookup result, payload size, per-attempt timing, and decoded undici error chains, to narrow down any residual failures.

Refs #19

Type of change

How to test

On WSL2 with a valid ANTHROPIC_API_KEY, run npm run dev and exercise audit → resolve → export end-to-end. The resolve step (larger payload) should no longer hang with ETIMEDOUT.
Run again with MINT_DEBUG=1 npm run dev and confirm [mint:debug] lines show the DNS lookup returning family:4 first and a successful first attempt in normal latency (~10–20s for resolve/export).
Sanity-check on native Windows / Linux that nothing regresses (still single attempt, no debug noise without the env var).

Checklist

npx tsc --noEmit passes with no errors
Tested with real CSS input through the full audit → tokens → export flow
UI is responsive on mobile (tested at 375px width) — N/A, no UI changes
No new Spanish strings introduced — all user-facing text is English
No hardcoded colors or values that should be CSS variables

Generated by Claude Code

WSL2's NAT frequently resolves api.anthropic.com to an IPv6 address that isn't routable from the guest, causing fetch() to hang until ETIMEDOUT on the larger payloads of the resolve and export steps (issue #19). Calling dns.setDefaultResultOrder('ipv4first') at module load applies the fix to both the CLI and the Next.js API routes without any user-facing configuration. The override is skipped if the user already set --dns-result-order via NODE_OPTIONS. Refs #19

Even with ipv4first DNS, the first fetch under WSL2 occasionally fails with ETIMEDOUT before subsequent attempts succeed (observed on resolve). Retry up to twice with 500ms / 1500ms backoff, but only for network-level errors (ETIMEDOUT, ECONNRESET, undici socket/connect errors, etc.). HTTP responses are still surfaced as-is to avoid masking real API errors. Refs #19

To narrow down the residual ETIMEDOUTs on WSL2 (issue #19), opt-in debug logging via MINT_DEBUG=1 prints: - DNS lookup result for api.anthropic.com (addresses + family) - Payload size and maxTokens per call - Per-attempt POST start, elapsed ms on failure, and decoded error codes (including undici cause chains: ETIMEDOUT, address, port, etc.) - Retry scheduling No behavior change when MINT_DEBUG is unset. Refs #19

nujovich · 2026-05-07T16:28:02Z

PR remains in draft until we find more stable sessions

Copilot

Pull request overview

Mitigates WSL2-specific fetch() timeouts when calling the Anthropic API by adjusting DNS resolution defaults, adding targeted retries for transient network failures, and introducing optional debug diagnostics for network troubleshooting.

Changes:

Force IPv4-first DNS result ordering at module load (unless NODE_OPTIONS already includes a --dns-result-order setting).
Add retry/backoff behavior to callAnthropic for selected transient network error codes.
Add opt-in MINT_DEBUG logging for DNS resolution, payload size, and per-attempt timing/error details.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+// WSL2's NAT often resolves api.anthropic.com to an IPv6 address that isn't
+// routable, causing fetch() to hang until ETIMEDOUT (issue #19). Forcing IPv4
+// first avoids the hang on WSL2 and is a no-op on hosts where IPv6 works.
+// Honors NODE_OPTIONS=--dns-result-order=... if the user already set it.
+if (!process.env.NODE_OPTIONS?.includes('--dns-result-order')) {


+import { setDefaultResultOrder, lookup as dnsLookup } from 'node:dns'
+
+// WSL2's NAT often resolves api.anthropic.com to an IPv6 address that isn't
+// routable, causing fetch() to hang until ETIMEDOUT (issue #19). Forcing IPv4
+// first avoids the hang on WSL2 and is a no-op on hosts where IPv6 works.
+// Honors NODE_OPTIONS=--dns-result-order=... if the user already set it.
+if (!process.env.NODE_OPTIONS?.includes('--dns-result-order')) {


+  const backoffsMs = [500, 1500]
+  let lastErr
+  if (DEBUG) {
+    const dns = await dnsLookupAll(ANTHROPIC_HOST)
+    debugLog(`dns ${ANTHROPIC_HOST} ->`, JSON.stringify(dns))
+    debugLog(`payload bytes=${Buffer.byteLength(body)} maxTokens=${maxTokens}`)
+  }
+  for (let attempt = 0; attempt <= backoffsMs.length; attempt++) {
+    const startedAt = Date.now()
+    try {
+      debugLog(`attempt ${attempt + 1}/${backoffsMs.length + 1} -> POST ${ANTHROPIC_URL}`)
+      const res = await fetch(ANTHROPIC_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': apiKey,
+          'anthropic-version': '2023-06-01',
+        },
+        body,
+      })
+      const data = await res.json()
+      if (!res.ok) {
+        const msg = data?.error?.message || `Anthropic API error (${res.status})`
+        throw new Error(msg)
+      }
+      const block = (data.content || []).find((b) => b && b.type === 'text')
+      return block ? block.text : ''
+    } catch (err) {
+      lastErr = err
+      const elapsed = Date.now() - startedAt
+      debugLog(`attempt ${attempt + 1} failed in ${elapsed}ms: ${describeError(err)}`)
+      if (attempt < backoffsMs.length && isRetryableNetworkError(err)) {
+        debugLog(`retrying in ${backoffsMs[attempt]}ms`)
+        await new Promise((r) => setTimeout(r, backoffsMs[attempt]))
+        continue
+      }
+      throw err
+    }
  }
-  const block = (data.content || []).find((b) => b && b.type === 'text')
-  return block ? block.text : ''
+  throw lastErr


…sl-hPGUs

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

lib/prompts.mjs:466

The PR description mentions retrying callAnthropic with backoff on transient network errors, but callAnthropic still performs a single fetch() and the new isRetryableNetworkError/RETRYABLE_NET_CODES helpers are unused. Either implement the retry loop as described (ensuring only network failures are retried) or remove the unused retry scaffolding.

// Network errors that benefit from a retry under WSL2's flaky NAT (issue #19).
// HTTP errors (4xx/5xx) are NOT retried — they're surfaced as-is.
const RETRYABLE_NET_CODES = new Set([
  'ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'EAI_AGAIN',
  'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT',
])

function isRetryableNetworkError(err) {
  const codes = []
  if (err?.code) codes.push(err.code)
  if (err?.cause?.code) codes.push(err.cause.code)
  for (const inner of err?.cause?.errors || []) {
    if (inner?.code) codes.push(inner.code)
  }
  return codes.some((c) => RETRYABLE_NET_CODES.has(c))
}

export async function callAnthropic({ apiKey, prompt, maxTokens = 3000 }) {
  if (!apiKey) {
    throw new Error('ANTHROPIC_API_KEY is required')
  }
  const res = await fetch(ANTHROPIC_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
      'anthropic-version': '2023-06-01',
    },
    body: JSON.stringify({
      model: MODEL,
      max_tokens: maxTokens,
      messages: [{ role: 'user', content: prompt }],
    }),
  })
  const data = await res.json()
  if (!res.ok) {
    const msg = data?.error?.message || `Anthropic API error (${res.status})`
    throw new Error(msg)
  }

nujovich · 2026-05-11T14:01:39Z

 export async function callAnthropic({ apiKey, prompt, maxTokens = 3000 }) {
  if (!apiKey) {
    throw new Error('ANTHROPIC_API_KEY is required')


@copilot restore "/ v8 ignore start */" marker

Already restored in b3af586 — both /* v8 ignore start */ (line 467) and /* v8 ignore end */ (line 504) are now in place and balanced around the network I/O block.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/nujovich/mint/sessions/99b96029-e555-459d-a11c-a1bd6069b190

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

+// WSL2's NAT often resolves api.anthropic.com to an IPv6 address that isn't
+// routable, causing fetch() to hang until ETIMEDOUT (issue #19). Forcing IPv4
+// first avoids the hang on WSL2 and is a no-op on hosts where IPv6 works.
+// Honors user-provided --dns-result-order from NODE_OPTIONS or CLI args.
+if (!hasDnsResultOrderOverride()) {


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/nujovich/mint/sessions/eaee4465-8cd2-4d9e-94b4-271423f172d5

- Updated vitest import to include vi and afterEach for test setup/teardown - Added callAnthropic to the prompts.mjs imports - All 35 existing tests pass This prepares for Task 3: Adding callAnthropic tests

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

nujovich · 2026-05-11T17:25:25Z

+export function hasDnsResultOrderOverride() {
+  if (process.env.NODE_OPTIONS?.includes('--dns-result-order')) return true
+
+  for (let i = 0; i < process.execArgv.length; i++) {
+    const arg = process.execArgv[i]
+    if (arg === '--dns-result-order') return true
+    if (arg?.startsWith('--dns-result-order=')) return true
+  }
+
+  return false
+}
+
+// Returns true when running inside WSL2 (Windows Subsystem for Linux v2).
+// WSL2 always sets WSL_DISTRO_NAME; WSL_INTEROP is a fallback for edge cases.
+// /proc/version contains "microsoft" on WSL2 kernels as a belt-and-suspenders
+// check if neither env var is present.
+export function isWSL2() {
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true
+  try {
+    return /microsoft/i.test(readFileSync('/proc/version', 'utf8'))
+  } catch {
+    return false
+  }
+}


@copilot move hasDnsResultOrderOverride and isWSL2 into a separated internal module that tests can import

Done in c49aa24. Both helpers are now in lib/net-utils.mjs (not in files / public API). lib/prompts.mjs imports them without re-exporting. Tests moved to lib/__tests__/net-utils.test.mjs with cases updated to match the current kernel-file-based isWSL2 implementation — all 47 tests pass with 100% function coverage.

+export function isWSL2() {
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true
+  try {
+    return /microsoft/i.test(readFileSync('/proc/version', 'utf8'))
+  } catch {
+    return false
+  }


nujovich · 2026-05-11T17:27:00Z

+  /* v8 ignore start */
+  if (DEBUG) {
+    const dns = await dnsLookupAll(ANTHROPIC_HOST)
+    debugLog(`dns ${ANTHROPIC_HOST} ->`, JSON.stringify(dns))
+    debugLog(`payload bytes=${Buffer.byteLength(body)} maxTokens=${maxTokens}`)
  }
-  const block = (data.content || []).find((b) => b && b.type === 'text')
-  return block ? block.text : ''
+  for (let attempt = 0; attempt <= backoffsMs.length; attempt++) {
+    const startedAt = Date.now()
+    try {
+      debugLog(`attempt ${attempt + 1}/${backoffsMs.length + 1} -> POST ${ANTHROPIC_URL}`)
+      const res = await fetch(ANTHROPIC_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': apiKey,
+          'anthropic-version': '2023-06-01',
+        },
+        body,
+      })
+      const data = await res.json()
+      if (!res.ok) {
+        const msg = data?.error?.message || `Anthropic API error (${res.status})`
+        throw new Error(msg)
+      }
+      const block = (data.content || []).find((b) => b && b.type === 'text')
+      return block ? block.text : ''
+    } catch (err) {
+      const elapsed = Date.now() - startedAt
+      if (DEBUG) {
+        debugLog(`attempt ${attempt + 1} failed in ${elapsed}ms: ${describeError(err)}`)
+      }
+      if (attempt < backoffsMs.length && isRetryableNetworkError(err)) {
+        debugLog(`retrying in ${backoffsMs[attempt]}ms`)
+        await new Promise((r) => setTimeout(r, backoffsMs[attempt]))
+        continue
+      }
+      throw err
+    }
+  }
+  /* v8 ignore end */


@copilot apply changes based on this feedback

Done in 5b3fe10. The broad /* v8 ignore start/end */ blocks around both isRetryableNetworkError and the retry loop body are removed. Now only the two truly untestable if (DEBUG) branches are marked with targeted /* v8 ignore next 5 */ and /* v8 ignore next 3 */. The retry loop, error checking, isRetryableNetworkError, and setTimeout delay are all now covered by the new tests.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…et-utils.mjs Agent-Logs-Url: https://github.com/nujovich/mint/sessions/42602eac-c540-4ed8-b7a6-bb49822c56f3

…hropic Agent-Logs-Url: https://github.com/nujovich/mint/sessions/adbc2709-f51d-44ad-9ddc-740aeb4045db

Agent-Logs-Url: https://github.com/nujovich/mint/sessions/adbc2709-f51d-44ad-9ddc-740aeb4045db

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

claude added 3 commits May 7, 2026 15:24

nujovich added bug Something isn't working research labels May 7, 2026

nujovich requested a review from Copilot May 7, 2026 16:29

Copilot started reviewing on behalf of nujovich May 7, 2026 16:29 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into claude/fetch-issues-w…

3a5c910

…sl-hPGUs

nujovich requested a review from Copilot May 11, 2026 13:21

Copilot started reviewing on behalf of nujovich May 11, 2026 13:21 View session

Copilot AI reviewed May 11, 2026

View reviewed changes

Potential fix for pull request finding

4688676

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of nujovich May 11, 2026 13:39 View session

fix: wire debug diagnostics and retry logic into callAnthropic

b3af586

Agent-Logs-Url: https://github.com/nujovich/mint/sessions/99b96029-e555-459d-a11c-a1bd6069b190

Copilot finished work on behalf of nujovich May 11, 2026 13:43

Copilot started work on behalf of nujovich May 11, 2026 14:02 View session

nujovich requested a review from Copilot May 11, 2026 14:03

Copilot started reviewing on behalf of nujovich May 11, 2026 14:04 View session

Copilot stopped work on behalf of nujovich due to an error May 11, 2026 14:05
Copilot encountered an unknown Git error. If the problem persists, please contact GitHub Support. To retry, leave a comment on this pull request asking Copilot to try again.

Copilot AI reviewed May 11, 2026

View reviewed changes

Potential fix for pull request finding

a126403

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of nujovich May 11, 2026 14:33 View session

fix: narrow setDefaultResultOrder('ipv4first') to WSL2 only

f537abc

Agent-Logs-Url: https://github.com/nujovich/mint/sessions/eaee4465-8cd2-4d9e-94b4-271423f172d5

Copilot finished work on behalf of nujovich May 11, 2026 14:37

nujovich added 4 commits May 11, 2026 17:16

chore: exclude network/debug helpers from v8 coverage

041bf1b

feat: add callAnthropic import and vi/afterEach to test skeleton

a5a6c40

- Updated vitest import to include vi and afterEach for test setup/teardown - Added callAnthropic to the prompts.mjs imports - All 35 existing tests pass This prepares for Task 3: Adding callAnthropic tests

test: add callAnthropic unit tests to close coverage gaps

7261b4a

feat: export isWSL2 and hasDnsResultOrderOverride for unit testing

c66fc1b

nujovich added 3 commits May 11, 2026 18:53

test: add node:fs mock and new imports for WSL2 detection tests

f85017d

test: add hasDnsResultOrderOverride unit tests

ecf1df8

test: add isWSL2 unit tests

6147513

nujovich requested a review from Copilot May 11, 2026 17:16

Copilot started reviewing on behalf of nujovich May 11, 2026 17:17 View session

Copilot AI reviewed May 11, 2026

View reviewed changes

Copilot started work on behalf of nujovich May 11, 2026 17:25 View session

nujovich and others added 2 commits May 11, 2026 19:25

Potential fix for pull request finding

bc3b766

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

refactor: move hasDnsResultOrderOverride and isWSL2 to internal lib/n…

c49aa24

…et-utils.mjs Agent-Logs-Url: https://github.com/nujovich/mint/sessions/42602eac-c540-4ed8-b7a6-bb49822c56f3

Copilot finished work on behalf of nujovich May 11, 2026 17:30

Copilot started work on behalf of nujovich May 11, 2026 17:30 View session

Copilot AI added 2 commits May 11, 2026 17:36

test: add retry/backoff tests and narrow v8 ignore regions in callAnt…

5b3fe10

…hropic Agent-Logs-Url: https://github.com/nujovich/mint/sessions/adbc2709-f51d-44ad-9ddc-740aeb4045db

refactor: rename nonRetryable to nonRetryableError for clarity

c2851e6

Agent-Logs-Url: https://github.com/nujovich/mint/sessions/adbc2709-f51d-44ad-9ddc-740aeb4045db

Copilot finished work on behalf of nujovich May 11, 2026 17:38

nujovich requested a review from Copilot May 11, 2026 17:47

Copilot started reviewing on behalf of nujovich May 11, 2026 17:48 View session

Copilot AI reviewed May 11, 2026

View reviewed changes

Comment thread lib/prompts.mjs

Comment thread lib/net-utils.mjs Outdated

Potential fix for pull request finding

e2f58f3

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Conversation

nujovich commented May 7, 2026

Summary

Type of change

How to test

Checklist

Uh oh!

nujovich commented May 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

nujovich May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

nujovich May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nujovich May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants