---
title: Error Handling
description: Empathetic error messages, graceful degradation, and helpful recovery
tags: [ux, resilience, empathy]
dependencies: [conversation, safety]
---

# Error Handling

Errors are inevitable. How an agent handles them determines whether users feel helped or abandoned.

## Principles

Errors are conversations, not dead ends. Be specific, not vague. Separate user errors from system errors.

A good error message has three parts:

```
Your file couldn't be uploaded.           ← what happened
The image is 15MB, but the limit is 5MB.  ← why
Try compressing it or choosing a smaller image. ← what to do
```

## Graceful degradation

When a feature fails, the rest continues:

- External LLM or Embedding db down → use local inference server (Ollama, llama.cpp)
- Local inference server unavailable → downgrade to in-browser inference (WebLLM)
- External execution environment down → use local execution or Edge-Containers
- API down → show cached data with a staleness indicator
- Non-critical feature fails → hide it, don't break the page
- Partial success → save what worked, report what didn't

## Retry strategies

- **Exponential backoff** for server errors (1s, 2s, 4s, 8s)
- **Immediate retry** for timeouts (once)
- **No retry** for client errors (4xx)
- **User-initiated retry** for ambiguous failures

## For agents

1. Acknowledge the error immediately
2. Explain what you tried and what failed
3. Suggest alternatives
4. If recoverable, attempt recovery transparently
5. If not, preserve the user's work
6. Never silently swallow errors