#19128: fix(errors): include agent/workspace context in 401 auth error messages
agents
size: XS
Cluster:
Error Handling Improvements
## Summary
Fixes #19117
When a provider API returns a 401 authentication error, the formatted error message now includes the **agent ID** and **workspace path** to help identify which configuration has an invalid API key — especially useful when running multiple agents simultaneously.
## Before / After
**Before:**
```
HTTP 401: authentication_error: Invalid bearer token (request_id: req_abc123)
```
**After:**
```
HTTP 401: authentication_error: Invalid bearer token [agent: myf, workspace: /Users/pierre/clawd-MYF] (request_id: req_abc123)
```
## Implementation
All changes are in `src/agents/pi-embedded-helpers/errors.ts`:
- **`AgentErrorContext` type** — new exported type `{ agentId?: string; workspacePath?: string }`
- **`formatRawAssistantErrorForUi(raw, agentCtx?)`** — adds optional second parameter; injects `[agent: …, workspace: …]` between the error message and request_id **only for HTTP 401 responses**
- **`resolveAgentErrorContext(opts)`** — private helper that derives agent ID and workspace path from the existing `cfg`/`sessionKey` options already threaded through `formatAssistantErrorText`
- **`formatAssistantErrorText`** — passes resolved context when calling `formatRawAssistantErrorForUi`
The context injection is strictly scoped to 401 errors; all other error paths are unchanged. Callers that invoke `formatRawAssistantErrorForUi` directly (e.g. TUI formatters) receive no context and are unaffected.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR enhances 401 authentication error messages by appending agent ID and workspace path context, helping users identify which agent configuration has an invalid API key when running multiple agents simultaneously.
- Adds `AgentErrorContext` type and `resolveAgentErrorContext` helper to derive agent/workspace info from existing config options
- Injects `[agent: <id>, workspace: <path>]` into formatted 401 error messages only, keeping all other error paths unchanged
- Context injection is limited to `formatAssistantErrorText` calling `formatRawAssistantErrorForUi`; direct callers (TUI formatters, `sanitizeUserFacingText`, `payloads.ts`) are unaffected
- The context will also appear for single-agent setups (showing `[agent: main, workspace: ...]`) since `resolveSessionAgentId` defaults to `"main"` — consider gating on multi-agent config to reduce noise
<h3>Confidence Score: 4/5</h3>
- This PR is safe to merge with minimal risk — changes are narrowly scoped to 401 error formatting only
- The change is small, well-targeted, and backward-compatible. The two suggestions (try-catch defensiveness and single-agent gating) are improvements rather than blockers. No existing behavior is broken for non-401 errors or for callers that do not pass agent context.
- No files require special attention — the single changed file is straightforward
<sub>Last reviewed commit: 3ea9a3e</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#19451: fix(errors): surface provider hint for role-ordering failures
by rafaelipuente · 2026-02-17
74.5%
#11821: fix(auth): trigger failover on 401 status code from expired OAuth t...
by AnonO6 · 2026-02-08
73.6%
#4036: fix: include cause detail in agent connection error diagnostic
by anajuliabit · 2026-01-29
72.9%
#22917: fix: Use agent's configured workspace when spawned as subagent
by jriff · 2026-02-21
72.7%
#15792: fix: pass agentId to resolveSessionFilePath in additional call sites
by MisterGuy420 · 2026-02-13
72.5%
#15982: fix: pass agentId to resolveSessionFilePath in reply flow (NX-003)
by automagik-genie · 2026-02-14
72.4%
#7301: fix(hooks): use resolveAgentIdFromSessionKey instead of split(":")[0]
by tsukhani · 2026-02-02
72.4%
#18647: fix(agents): guard against undefined paths in injectedFiles
by kleinpanic · 2026-02-16
72.4%
#19412: fix(status): prefer configured contextTokens over session entry
by rafaelipuente · 2026-02-17
72.2%
#14368: fix: skip auth profile cooldown on format errors to prevent provide...
by koatora20 · 2026-02-12
71.8%