#4036: fix: include cause detail in agent connection error diagnostic
gateway
## Summary
- Add `describeNetworkError()` helper to `src/infra/errors.ts` that extracts one level of `.cause` from network errors (e.g. Anthropic SDK's `APIConnectionError`) and appends the underlying code or message
- Use it in the agent catch block (`src/gateway/server-methods/agent.ts`) so users see e.g. `Connection error. (UNABLE_TO_VERIFY_LEAF_SIGNATURE)` instead of just `Connection error.`
- Add tests for the new function and existing error utilities in `src/infra/errors.test.ts`
## Test plan
- [x] `pnpm build` — type-check passes
- [x] `pnpm test src/infra/errors` — 16 tests pass
- [x] `pnpm lint` — clean
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds a new `describeNetworkError()` helper (`src/infra/errors.ts`) that formats network-related errors by extracting a single level of `err.cause` and appending either the underlying `code` or `message`. The agent request handler (`src/gateway/server-methods/agent.ts`) now uses that helper when returning `UNAVAILABLE` errors so clients see more diagnostic detail. A new `src/infra/errors.test.ts` file provides unit coverage for `extractErrorCode`, `formatErrorMessage`, `formatUncaughtError`, and the new `describeNetworkError`.
<h3>Confidence Score: 4/5</h3>
- This PR is generally safe to merge and improves error diagnostics with minimal behavioral change.
- Changes are localized (new helper + wiring in one catch block) and are covered by focused unit tests. The main remaining concern is edge cases where thrown values or causes are non-Error objects, which may lead to low-signal summaries (e.g., JSON stringification like "{}").
- src/infra/errors.ts (edge-case formatting for non-Error throws/causes)
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#7229: fix: add network error resilience to agentic loop failover
by ai-fanatic · 2026-02-02
79.1%
#15163: fix(errors): classify connection errors as retryable failover reason
by fagemx · 2026-02-13
78.5%
#9232: Fix: Add automatic retry for network errors in message runs
by vishaltandale00 · 2026-02-05
77.9%
#2541: fix(agents): add error handling to orphaned message cleanup
by Episkey-G · 2026-01-27
77.7%
#19077: fix(agents): trigger model failover on connection-refused and netwo...
by ayanesakura · 2026-02-17
77.7%
#12314: fix: treat HTTP 5xx server errors as failover-worthy
by hsssgdtc · 2026-02-09
77.6%
#7563: fix: expand transient network error detection
by kaigritun · 2026-02-03
77.5%
#7141: fix(telegram): unify network error detection to prevent poll crashes
by hclsys · 2026-02-02
77.1%
#15109: fix: distinguish transient API errors from billing errors
by jwchmodx · 2026-02-13
76.9%
#5031: fix: add network connection error codes to failover classifier
by shayan919293 · 2026-01-30
76.4%