LWC: Apex Error Boundary
Centralized error handling pattern for Lightning Web Components with retry support, error categorization, and consistent user experience.
📖 Project Overview
Apex Error Boundary is a reusable Lightning Web Component pattern designed to centralize client-side error handling across Salesforce applications.
Instead of implementing duplicate error handling logic in every component, child LWCs simply dispatch a standard apexerror event when a wire adapter, imperative Apex call, or server operation fails.
The boundary component captures the error, categorizes it, displays a user-friendly UI, and optionally allows retrying failed operations.
✨ Key Features
| Feature | Description |
|---|---|
| Centralized Error Handling | Single component handles all Apex and Wire errors. |
| Reusable Architecture | Drop into any Salesforce project. |
| Retry Support | Allow users to retry failed operations. |
| Technical Details Mode | Optional expandable debugging information. |
| Error Categorization | Converts raw Salesforce errors into user-friendly messages. |
| Event Driven | Uses custom events for loose coupling. |
🏗 Architecture Overview
Parent Page
│
└── c-apex-error-boundary
│
▼
Child Components
│
├── @wire calls
├── Imperative Apex
└── DML Operations
│
▼
dispatchEvent('apexerror')
│
▼
Boundary Captures Error
│
▼
Error Classification
│
▼
Friendly Error UI
│
▼
Retry / Dismiss
📁 Repository Structure
apexErrorBoundary │ ├── classes │ └── ExampleApexController.cls │ ├── lwc │ ├── apexErrorBoundary │ ├── apexErrorUtils │ ├── exampleApexChild │ └── accountRecordPage │ ├── staticresources ├── permissionsets └── README.md
⚙️ Apex Controller Example
@AuraEnabled(cacheable=true)
public static Account getAccountDetails(Id accountId) {
try {
return [
SELECT Id, Name, Industry
FROM Account
WHERE Id = :accountId
LIMIT 1
];
} catch (QueryException qe) {
throw new AuraHandledException(
'The account record could not be retrieved.'
);
}
}
💻 Boundary Component Highlights
@api customTitle; @api fallbackMessage; @api maxRetries = 3; @api showTechnicalDetails = false; @api allowDismiss = false; @track showError = false; @track showChild = true; @track isRetrying = false;
🔄 Runtime Error Flow
- Child component executes Wire or Apex call.
- Failure occurs.
- Component dispatches apexerror event.
- Error Boundary intercepts event.
- Error is parsed and categorized.
- User-friendly error message is displayed.
- User can retry the operation.
🧩 Usage Example
<c-apex-error-boundary custom-title="Account Information" max-retries="3" show-technical-details="true">
<c-example-apex-child record-id="{recordId}">
</c-example-apex-child>
</c-apex-error-boundary>
📂 Error Categories
- Validation Errors
- DML Exceptions
- SOQL Query Failures
- Permission Errors
- Network Errors
- Unknown Exceptions
🚀 Benefits
- Consistent UX across Salesforce applications.
- Reduces duplicate error handling code.
- Improves maintainability.
- Simplifies debugging and support.
- Provides enterprise-grade error management.
📦 Deployment
sf org login web -a myOrg sf project deploy start \ --source-dir force-app \ -o myOrg
📌 Conclusion
Apex Error Boundary provides a robust, reusable, and scalable solution for handling Salesforce Apex and Wire errors in Lightning Web Components. By centralizing error management, teams can improve user experience, reduce duplicate code, and simplify long-term maintenance.
