---
name: Error Recovery Patterns
slug: error-recovery-patterns
category: DevOps
description: Error Recovery Patterns provides guidance for implementing retry logic, circuit breakers, exponential backoff, error categorization, and debug logging to reduce retry loops and handle transient failures in automated agent workflows. Use it when adding recovery strategies for network operations, installations, or API calls.
github: "https://github.com/github/gh-aw/tree/main/.github/skills/error-recovery-patterns"
language: Go
stars: 4934
forks: 495
install: "npx degit https://github.com/github/gh-aw/tree/main/.github/skills/error-recovery-patterns ~/.claude/skills/error-recovery-patterns"
installs_to: ~/.claude/skills/error-recovery-patterns
source_path: .github/skills/error-recovery-patterns/SKILL.md
collection_size: 25
category_size: 798
collection_url: "https://dirskills.com/collections/github/gh-aw"
added: 2026-08-16T07:00:56.340Z
last_synced: 2026-08-16T07:00:56.340Z
canonical_url: "https://dirskills.com/skills/error-recovery-patterns"
---

# Error Recovery Patterns

Error Recovery Patterns provides guidance for implementing retry logic, circuit breakers, exponential backoff, error categorization, and debug logging to reduce retry loops and handle transient failures in automated agent workflows. Use it when adding recovery strategies for network operations, installations, or API calls.

**Install:**

```bash
npx degit https://github.com/github/gh-aw/tree/main/.github/skills/error-recovery-patterns ~/.claude/skills/error-recovery-patterns
```

## README

# Error Recovery Patterns Skill

Use this skill for error handling, recovery strategies, and debugging in gh-aw.

## Purpose

Implement robust recovery patterns to:
- Reduce retry loops in agent sessions (target: <10% vs current 23%)
- Implement circuit breakers to prevent infinite retry loops
- Add proactive recovery for installation, dependency, and API failures
- Improve debug logging for recovery attempts

## When to Use This Skill

Use this skill when:
- Implementing retry logic for network operations, installations, or API calls
- Debugging retry loop issues in workflows or agent sessions
- Adding error recovery patterns to new or existing code
- Understanding transient vs non-transient error classification
- Implementing circuit breakers or exponential backoff
- Adding debug logging for recovery attempts

## Key Concepts Covered

### 1. Circuit Breaker Pattern
- Maximum retry limits (standard: 3 attempts)
- Exponential backoff strategies
- Fail-fast on non-transient errors
- Implementation in JavaScript, Shell, and Go

### 2. Installation Failure Recovery
- NPM installation with cache clearing and registry fallbacks
- Python pip installation with mirror alternatives
- Docker image pull with retry and rate limit handling
- Copilot CLI installation with network retry

### 3. API Timeout and Rate Limit Handling
- GitHub API rate limit detection and backoff
- Transient error detection patterns
- Custom retry configuration for different APIs
- Rate limit-specific retry strategies

### 4. Debug Logging for Recovery
- Logger package usage for retry attempts
- Category naming conventions (pkg:filename)
- DEBUG environment variable patterns
- Zero-overhead logging when disabled

### 5. Error Categorization
- Transient vs non-transient errors
- Network errors, timeout patterns
- HTTP error codes (502, 503, 504)
- GitHub-specific errors (rate limits, abuse detection)

## Anti-Patterns to Avoid

This skill explicitly covers anti-patterns to avoid:
- ❌ Infinite retry loops without maximum limits
- ❌ Retrying validation errors that won't self-correct
- ❌ No backoff delay between attempts
- ❌ Silent retries without logging
- ❌ Retrying non-transient errors

## Code Examples Provided

The skill includes production-ready examples for:
- JavaScript retry with `withRetry()` function
- Shell script retry loops with exponential backoff
- Go retry patterns with context and timeouts
- NPM/pip/docker installation recovery
- GitHub API rate limit handling
- Debug logging for all recovery attempts

## Related Skills

- **error-messages** - Error message formatting and style guide
- **error-pattern-safety** - Safety guidelines for error pattern regex
- **developer** - General development guidelines and conventions

## Full Documentation

Complete documentation available at: `../../scratchpad/error-recovery-patterns.md`

This skill references the comprehensive error recovery patterns document which includes:
- Console formatting requirements
- Error wrapping patterns
- Common error scenarios with step-by-step resolution
- Error message templates
- Debugging runbook
- Error categorization decision trees
- Metrics and monitoring strategies