JavaScript Async Error Handling
Reviews and refactors asynchronous JavaScript error handling so Promise-based code avoids swallowed failures, unhandled rejections, unclear fallback behavior, and weak failure contracts.
SKILL.mdskills/javascript/async-error-handling/SKILL.md
GitHubJavaScript Async Error Handling
Purpose
Use this skill to review, refactor, or implement safe error handling for asynchronous JavaScript code.
The goal is to prevent swallowed errors, unhandled promise rejections, duplicated catch blocks, unclear control flow, and unsafe fallback behavior.
This skill applies to plain JavaScript, TypeScript, Node.js, browser code, frontend services, API clients, scripts, and test utilities.
When to Use
Use this skill when the task involves:
async/await- Promises
try/catch.then()/.catch()chains- API request error handling
- retry logic
- fallback values
- error propagation
- unhandled promise rejection warnings
- async code inside loops, callbacks, or event handlers
When Not to Use
Do not use this skill when:
- the task is only about synchronous validation
- the problem belongs specifically to RxJS Observable error handling
- the task is only about HTTP status mapping in a framework-specific interceptor
- the code already has a domain-level error strategy and the request does not ask to change it
- the change would hide business errors behind generic fallbacks
Do
Identify every async boundary involved in the requested change:
- public async functions
- event handlers
- API calls
- service methods
- promise chains
- dynamic imports
- file/network operations
- timers
- task queues
- test setup and teardown
Choose one explicit error contract per boundary:
- throw or reject when the caller must handle the failure
- return a typed result object when failure is part of normal flow
- return a fallback only when the fallback is correct and safe
- log and rethrow when the failure must be observable upstream
Prefer async / await for imperative flows:
async function loadUser(userId) {
try {
return await userApi.getUser(userId);
} catch (error) {
throw new Error("Unable to load user", { cause: error });
}
}
Never swallow errors silently:
try {
await saveData(data);
} catch (error) {
logger.warn("Save failed", error);
throw error;
}
Preserve stack and context when wrapping errors.
Avoid catch-all fallbacks unless empty data is semantically valid.
Handle parallel async flows intentionally:
Promise.allfor all-or-nothing workPromise.allSettledfor valid partial success
Avoid floating promises unless intentionally fire-and-forget:
void saveAuditLog(payload).catch((error) => {
logger.warn("Audit log failed", error);
});
Use for...of with await for sequential async loops and Promise.all for parallel loops.
Test failure paths:
- rejected promise
- thrown async error
- fallback branch
- retry exhaustion
- partial success
- error propagation
Do Not
Avoid empty catch blocks.
Avoid returning fake success from failed async work.
Avoid forEach with async callbacks.
Avoid unhandled promise rejections.
Avoid Promise.allSettled when fail-fast behavior is required.
Avoid retries without backoff or limits.
Avoid masking authentication or authorization failures as empty data.
Review Checklist
- Every Promise is awaited, returned, or explicitly handled.
- Every catch block either recovers safely or rethrows.
- Fallback values are semantically valid.
- User-facing errors are separated from technical errors.
- Failure paths are tested.
- No unrelated async refactor was introduced.
Expected Output
- Identify async boundaries.
- Choose a clear error contract.
- Preserve stack and context.
- Avoid swallowed or floating failures.
- Add or update tests for success and failure paths.