# Error Handling System

# Error Handling System

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [src/lib/components/toasts/EventToast.svelte](src/lib/components/toasts/EventToast.svelte)
- [src/lib/components/ui/JsonTableViewer.svelte](src/lib/components/ui/JsonTableViewer.svelte)
- [src/lib/components/ui/rfc-error-dialog.svelte](src/lib/components/ui/rfc-error-dialog.svelte)
- [src/lib/errors/app-errors.ts](src/lib/errors/app-errors.ts)
- [src/lib/errors/rfc7807-mapper.ts](src/lib/errors/rfc7807-mapper.ts)
- [src/lib/errors/rfc7807.ts](src/lib/errors/rfc7807.ts)
- [src/lib/errors/toast.ts](src/lib/errors/toast.ts)
- [src/lib/shell/sheets/panels/ErrorsPanel.svelte](src/lib/shell/sheets/panels/ErrorsPanel.svelte)

</details>



The Primebrick Frontend implements a centralized error management pipeline designed to handle both local application errors and standardized backend responses. It utilizes a ring-buffer store for history, a multi-tier impact taxonomy, and a dedicated UI for deep inspection of complex error payloads.

## Impact Level Taxonomy

Errors are classified using an `ImpactLevel` to determine their visual priority and notification style [src/lib/errors/app-errors.ts:7-7]().

| Level | Description | UI Toast Variant | Sidebar Badge Tone |
| :--- | :--- | :--- | :--- |
| `CRITICAL` | System-wide failure or data loss risk. | `toast.critical` (Semaphore Red) | `danger` |
| `HIGH` | Standard functional error (e.g., API 500). | `toast.error` (Destructive) | `danger` |
| `MEDIUM` | Warning or non-blocking issue. | `toast.warning` (Amber) | `warning` |
| `LOW` | Informational or background notification. | `toast.info` (Sky Blue) | `info` |

**Sources:** [src/lib/errors/app-errors.ts:54-76](), [src/lib/shell/sheets/panels/ErrorsPanel.svelte:54-80]()

## The Error Pipeline

The system centralizes all errors into the `appErrors` writable store, which maintains a ring buffer capped at 50 entries to prevent memory leaks [src/lib/errors/app-errors.ts:15-35]().

### Data Flow Diagram
This diagram illustrates the transition from raw error triggers to UI representation.

```mermaid
graph TD
    subgraph "Error Entry Points"
        A["API Fetch (4xx/5xx)"] --> B["pushRFC7807Error()"]
        C["Local UI Logic"] --> D["pushAppError()"]
        E["Complex Operations"] --> F["pushImpactError()"]
    end

    subgraph "Core Logic (app-errors.ts)"
        B --> F
        D --> G["appErrors.update()"]
        F --> G
        G --> H{"Ring Buffer Cap (50)"}
        H --> I["appErrors Store"]
    end

    subgraph "UI Notification Space"
        F --> J["showImpactToast()"]
        J --> K["EventToast.svelte"]
        K --> L["svelte-sonner"]
    end

    subgraph "Inspection Space"
        I --> M["ErrorsPanel.svelte"]
        M --> N["RfcErrorDialog.svelte"]
        N --> O["JsonTableViewer.svelte"]
    end
```
**Sources:** [src/lib/errors/app-errors.ts:82-103](), [src/lib/errors/app-errors.ts:166-197](), [src/lib/shell/sheets/panels/ErrorsPanel.svelte:9-9]()

## RFC 7807 Problem Details

The backend communicates errors using the **RFC 7807 (Problem Details for HTTP APIs)** standard. The frontend consumes this via the `RFC7807Error` interface [src/lib/errors/rfc7807.ts:5-20]().

### Mapping and Translation
When a backend error is received:
1.  **Severity Mapping**: The `severity` field is mapped to an `ImpactLevel` (defaulting to `HIGH`) [src/lib/errors/app-errors.ts:153-159]().
2.  **Key Translation**: `mapRFC7807ToMessageKey` checks `status` and `internal_code` to return a user-friendly i18n key (e.g., mapping `account_locked` to `login.accountLocked`) [src/lib/errors/rfc7807-mapper.ts:7-36]().
3.  **Preservation**: Any non-standard fields (like `duplicateResults` or `issues`) are preserved in the `extraFields` object for the detailed viewer [src/lib/errors/app-errors.ts:179-196]().

## UI Components

### ErrorsPanel (`src/lib/shell/sheets/panels/ErrorsPanel.svelte`)
A global side-sheet that displays the history of `appErrors`.
*   Uses `EventCard` components to display error metadata, scope, and timestamps [src/lib/shell/sheets/panels/ErrorsPanel.svelte:136-190]().
*   Provides a "Clear All" action via `clearAppErrors()` [src/lib/shell/sheets/panels/ErrorsPanel.svelte:87-98]().
*   Triggers the `RfcErrorDialog` for entries containing `extra` data [src/lib/shell/sheets/panels/ErrorsPanel.svelte:191-201]().

### RfcErrorDialog (`src/lib/components/ui/rfc-error-dialog.svelte`)
A full-screen modal used for deep inspection of complex errors.
*   **Aesthetic Mode**: Uses `JsonTableViewer` to render structured data in a readable, recursive table format [src/lib/components/ui/rfc-error-dialog.svelte:155-161]().
*   **Raw Mode**: Uses the `shiki` highlighter to display the raw JSON payload with syntax highlighting [src/lib/components/ui/rfc-error-dialog.svelte:56-78]().
*   **Navigation**: Includes a `Dock` to switch between preview modes [src/lib/components/ui/rfc-error-dialog.svelte:123-144]().

### Code Entity Association
This diagram maps system behaviors to the specific code entities responsible for the error lifecycle.

```mermaid
graph LR
    subgraph "Natural Language"
        ERR["'Something went wrong'"]
        DETAIL["'Show me technical details'"]
        TOAST["'Show a popup notification'"]
    end

    subgraph "Code Entity Space"
        direction TB
        subgraph "Logic"
            pushRFC["pushRFC7807Error()"]
            pushImp["pushImpactError()"]
            mapRFC["mapRFC7807ToMessageKey()"]
        end
        
        subgraph "Storage"
            store["appErrors (Writable)"]
        end

        subgraph "UI Primitives"
            Dialog["rfc-error-dialog.svelte"]
            Viewer["JsonTableViewer.svelte"]
            EToast["EventToast.svelte"]
        end
    end

    ERR --> pushRFC
    pushRFC --> mapRFC
    mapRFC --> pushImp
    pushImp --> store
    pushImp --> TOAST
    TOAST --> EToast
    store --> DETAIL
    DETAIL --> Dialog
    Dialog --> Viewer
```
**Sources:** [src/lib/errors/app-errors.ts:166-166](), [src/lib/errors/rfc7807-mapper.ts:7-7](), [src/lib/components/ui/rfc-error-dialog.svelte:1-1](), [src/lib/components/toasts/EventToast.svelte:1-1]()

## Key Functions Reference

| Function | Purpose | File |
| :--- | :--- | :--- |
| `pushAppError` | Pushes a simple string-based error to the store and shows a toast. | [src/lib/errors/app-errors.ts:87-103]() |
| `pushImpactError` | Pushes a categorized error with support for i18n keys and extra metadata. | [src/lib/errors/app-errors.ts:105-143]() |
| `pushRFC7807Error` | Transforms a standard backend error response into an `AppError`. | [src/lib/errors/app-errors.ts:166-197]() |
| `toast.critical` | Displays a high-priority, persistent notification using `TOAST_CRITICAL_CLASS`. | [src/lib/errors/toast.ts:57-62]() |
| `mapSeverityToImpact` | Normalizes backend severity strings into `ImpactLevel` types. | [src/lib/errors/app-errors.ts:153-159]() |

**Sources:** [src/lib/errors/app-errors.ts:1-197](), [src/lib/errors/toast.ts:1-76]()

---