Copy page

Frontend

Error Handling System

Error Handling System

Relevant source files

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

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

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.

Code
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.

Code
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

---