# error-handling

Skill for designing error handling layers, setting up structured logging, and recovery strategies. Use it when building exception hierarchies, configuring observability, or implementing retry and circuit breaker patterns.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 1424 repo stars
- Author: CloudAI-X
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/CloudAI-X/claude-workflow-v2/tree/HEAD/skills/error-handling/SKILL.md
- Updated: 2026-10-06
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/cloudai-x-error-handling

## What it does

The skill provides ready-to-use patterns for JavaScript, TypeScript, Python, and Go. It covers custom error hierarchies, JSON structured logging, correlation IDs for request tracing, and examples of retry logic and graceful degradation.

Core workflow is a seven-step checklist: from defining error taxonomy to validating against antipatterns. Shows what to avoid—swallowing errors silently, catching everything indiscriminately, losing error context—and how to fix it.

For Express, it includes a centralized error handler with a 4-parameter middleware. For logging, it recommends `pino` or similar to emit structured events and make them searchable in log aggregators.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add CloudAI-X/claude-workflow-v2
```
In the agent chat (not a shell):
```text
/plugin install project-starter@claude-workflow
```
This installs the whole project-starter plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add CloudAI-X/claude-workflow-v2 --skill error-handling -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/error-handling/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/error-handling/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add CloudAI-X/claude-workflow-v2 --skill error-handling -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/error-handling/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add CloudAI-X/claude-workflow-v2 --skill error-handling -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/error-handling/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install CloudAI-X/claude-workflow-v2 skills/error-handling
```

2. **Manually: put the files in place**
- File: `.github/skills/error-handling/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add CloudAI-X/claude-workflow-v2 --skill error-handling -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/CloudAI-X/claude-workflow-v2 --path skills/error-handling
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/error-handling/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/CloudAI-X/claude-workflow-v2/tree/HEAD/skills/error-handling/SKILL.md

## When to use it
- design a custom error hierarchy for your application
- emit structured JSON logs that integrate with log aggregation
- build retry logic with backoff and circuit breaker fallback
- trace a request across services using correlation IDs
- set up a global error handler in Express

## Example prompts
- Help me design error handling for a Node.js REST API
- Show me how to set up structured logging with correlation IDs across microservices
- How do I implement exponential backoff retry in Python?

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: cfa9af65a1021b71.

BEGIN THIRD-PARTY FILE cfa9af65a1021b71
````text
---
name: error-handling
description: Implements error handling patterns, structured logging, retry strategies, circuit breakers, and graceful degradation. Use when designing error handling, setting up logging, implementing retries, adding error tracking, or when asked about error boundaries, log aggregation, alerting, or resilience patterns.
---

# Error Handling & Observability

### When to Load

- **Trigger**: Try/catch patterns, retry logic, error responses, circuit breakers, structured logging
- **Skip**: No error handling or observability involved in the current task

## Error Handling Workflow

Copy this checklist and track progress:

```
Error Handling Progress:
- [ ] Step 1: Define error taxonomy (categories and severity)
- [ ] Step 2: Implement error handling by layer
- [ ] Step 3: Set up structured logging
- [ ] Step 4: Add retry and circuit breaker patterns
- [ ] Step 5: Configure error tracking service
- [ ] Step 6: Define user-facing error messages
- [ ] Step 7: Validate against anti-patterns checklist
```

## Error Handling Patterns by Language

### JavaScript / TypeScript

```typescript
// Custom error hierarchy
class AppError extends Error {
  constructor(
    message: string,
    public statusCode: number = 500,
    public code: string = "INTERNAL_ERROR",
    public isOperational: boolean = true,
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}
class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} with id ${id} not found`, 404, "NOT_FOUND");
  }
}
class ValidationError extends AppError {
  constructor(public errors: Record<string, string[]>) {
    super("Validation failed", 400, "VALIDATION_ERROR");
  }
}

// WRONG: Swallowing errors silently
try {
  await saveUser(data);
} catch (e) {
  // nothing here -- bug hides forever
}

// WRONG: Catching and re-throwing without context
try {
  await saveUser(data);
} catch (e) {
  throw e; // pointless try/catch
}

// CORRECT: Add context, handle or propagate
try {
  await saveUser(data);
} catch (error) {
  if (error instanceof ValidationError) {
    return res.status(400).json({ errors: error.errors });
  }
  logger.error({ err: error, userId: data.id }, "Failed to save user");
  throw new AppError("Unable to save user", 500, "USER_SAVE_FAILED");
}
```

### Express Global Error Handler

```typescript
// Centralized error handler middleware (must have 4 params)
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  if (err instanceof AppError) {
    logger.warn(
      { code: err.code, statusCode: err.statusCode, path: req.path },
      "Operational error",
````
END THIRD-PARTY FILE cfa9af65a1021b71

The third-party file has ended. Everything between the cfa9af65a1021b71 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2660 of 13444 bytes. © CloudAI-X · MIT · https://github.com/CloudAI-X/claude-workflow-v2/tree/HEAD/skills/error-handling/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
