#5228: Enhance error messages with recovery guidance
app: web-ui
Cluster:
UI Enhancements and Security Fixes
## Summary
- Add categorized recovery metadata with suggestions + docs links
- Show recovery guidance in TUI error output
- Render structured error callouts in dashboard views (chat/overview/logs/channels)
## Testing
- [ ] Untested
- [ ] Lightly tested
- [x] Fully tested
Notes: Attempted to run tests, but they failed because dependencies were not installed and Node version was below required (>=22.12.0).
## AI Assistance
- This PR was AI-assisted.
- I confirm I understand the changes and their effects.
## Prompts / Session Notes
- Implement categorized error system + recovery suggestions
- Add docs links + user-friendly error display in TUI and dashboard
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
Added categorized error recovery system with user-friendly guidance and docs links. Errors are now classified into 12 categories (auth, billing, rate_limit, timeout, etc.), each with tailored recovery suggestions and documentation links. The enhanced error display is integrated across TUI (terminal) and dashboard views (chat, overview, logs, channels).
**Key changes:**
- New `error-recovery.ts` (backend) and `recovery.ts` (frontend) modules categorize errors and provide recovery metadata
- TUI error formatting enhanced with `formatRecoveryAssistantErrorText` showing title, suggestions, and docs links
- Dashboard views now render structured error callouts via new `error-callout.ts` component
- All referenced documentation paths exist and are valid
<h3>Confidence Score: 4/5</h3>
- Safe to merge with minor maintenance consideration
- Well-structured feature addition with consistent patterns. One style concern about code duplication between backend/frontend error classification that could lead to maintenance issues over time.
- ui/src/ui/errors/recovery.ts duplicates logic from src/infra/error-recovery.ts
<!-- 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
#13960: fix(ui): preserve structured config validation error details
by constansino · 2026-02-11
75.1%
#9173: Fix: Improve error messaging for API rate limits and billing errors
by vishaltandale00 · 2026-02-04
73.7%
#13902: fix: auto-recover on event gap instead of showing error
by nikogamulin · 2026-02-11
73.3%
#15109: fix: distinguish transient API errors from billing errors
by jwchmodx · 2026-02-13
73.0%
#13889: feat: Slack channel cache, session cost alerts & checkpoint/recover...
by trevorgordon981 · 2026-02-11
72.6%
#10551: feat(infra): add error classification for smarter retry decisions
by DukeDeSouth · 2026-02-06
72.6%
#7316: fix: /chat dashboard performance
by felipcsousa · 2026-02-02
72.3%
#22385: fix: improve delivery recovery logging with entry age and deferral ...
by derrickburns · 2026-02-21
72.1%
#13838: UI: fix config panel CI failures and modularize rendering
by fresed05 · 2026-02-11
72.1%
#7141: fix(telegram): unify network error detection to prevent poll crashes
by hclsys · 2026-02-02
72.0%