davila7/claude-code-templates / cli-tool/components/skills/development/error-resolver
Error Resolver
FlaggedSystematic error diagnosis and resolution using first-principle analysis. Use when encountering any error message, stack trace, or unexpected behavior. Supports replay functionality to record and reuse solutions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.9 KB |
| analysis/root-cause.md | markdown | 7.3 KB |
| analysis/stack-trace.md | markdown | 8.0 KB |
| patterns/database.md | markdown | 9.9 KB |
| patterns/docker.md | markdown | 9.1 KB |
| patterns/git.md | markdown | 8.9 KB |
| patterns/go.md | markdown | 8.8 KB |
| patterns/network.md | markdown | 11.6 KB |
| patterns/nodejs.md | markdown | 10.4 KB |
| patterns/python.md | markdown | 10.5 KB |
| patterns/react.md | markdown | 11.1 KB |
| patterns/rust.md | markdown | 10.5 KB |
| replay/README.md | markdown | 6.6 KB |
| replay/solution-template.yaml | config | 2.1 KB |
patterns/network.md
View on GitHub# Network & API Error Patterns
Common network and API errors with diagnosis and solutions.
## HTTP Status Errors
### 400 Bad Request
```
HTTP 400 Bad Request
{"error": "Bad Request", "message": "Invalid JSON"}
```
**Causes**:
1. Malformed JSON body
2. Missing required fields
3. Invalid field values
4. Wrong Content-Type header
**Diagnosis**:
```bash
# Validate JSON
echo '{"key": "value"}' | jq .
# Check request
curl -v -X POST https://api.example.com/endpoint \
-H "Content-Type: application/json" \
-d '{"key": "value"}'
```
**Solutions**:
```javascript
// Check Content-Type
fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json', // Not 'text/plain'
},
body: JSON.stringify(data), // Not just data
})
// Validate before sending
if (!data.required_field) {
throw new Error('Missing required_field')
}
```
---
### 401 Unauthorized
```
HTTP 401 Unauthorized
{"error": "Unauthorized", "message": "Invalid or expired token"}
```
**Causes**:
1. Missing auth token
2. Expired token
3. Invalid token format
4. Wrong auth scheme
**Solutions**:
```javascript
// Check Authorization header format
fetch(url, {
headers: {
'Authorization': `Bearer ${token}`, // Note: "Bearer " prefix
},
})
// Refresh token if expired
async function fetchWithAuth(url) {
let response = await fetch(url, {
headers: { 'Authorization': `Bearer ${accessToken}` }
})
if (response.status === 401) {
accessToken = await refreshToken()
response = await fetch(url, {
headers: { 'Authorization': `Bearer ${accessToken}` }
})
}
return response
}
```
---
### 403 Forbidden
```
HTTP 403 Forbidden
{"error": "Forbidden", "message": "Insufficient permissions"}
```
**Causes**:
1. Authenticated but not authorized
2. Resource access denied
3. Rate limiting
4. IP blocked
**Different from 401**: 401 = "Who are you?" 403 = "I know who you are, but no."
**Solutions**:
- Check user permissions/roles
- Verify API key scopes
- Check rate limit headers
- Verify IP whitelist
---
### 404 Not Found
```
HTTP 404 Not Found
{"error": "Not Found", "message": "Resource not found"}
```
**Causes**:
1. Wrong URL/endpoint
2. Resource deleted
3. ID doesn't exist
4. Trailing slash issues
**Diagnosis**:
```bash
# Check URL is correct
curl -I https://api.example.com/users/123
# Try with/without trailing slash
curl https://api.example.com/users/
curl https://api.example.com/users
```
**Solutions**:
```javascript
// Handle 404 gracefully
const response = await fetch(`/api/users/${id}`)
if (response.status === 404) {
return null // Or throw custom error
}
return response.json()
```
---
### 405 Method Not Allowed
```
HTTP 405 Method Not Allowed
{"error": "Method Not Allowed", "allowed": ["GET", "POST"]}
```
**Causes**:
1. Using wrong HTTP method
2. Endpoint doesn't support method
**Solutions**:
```bash
# Check allowed methods
curl -I -X OPTIONS https://api.example.com/endpoint
# Look for Allow header
# Use correct method
curl -X POST https://api.example.com/users # Not GET
```
---
### 429 Too Many Requests
```
HTTP 429 Too Many Requests
{"error": "Rate Limited", "retry_after": 60}
```
**Causes**:
1. Rate limit exceeded
2. Too many concurrent requests
**Solutions**:
```javascript
// Implement exponential backoff
async function fetchWithRetry(url, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url)
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || 60
await sleep(retryAfter * 1000 * (i + 1))
continue
}
return response
}
throw new Error('Max retries exceeded')
}
// Rate limiting in client
const limiter = new RateLimiter({
tokensPerInterval: 10,
interval: 'second',
})
async function limitedFetch(url) {
await limiter.removeTokens(1)
return fetch(url)
}
```
---
### 500 Internal Server Error
```
HTTP 500 Internal Server Error
```
**Causes**:
1. Server-side bug
2. Unhandled exception
3. Database error
4. Third-party service failure
**What you can do**:
1. Check if your request is valid
2. Retry later
3. Report to API provider with request details
---
### 502 Bad Gateway
```
HTTP 502 Bad Gateway
```
**Causes**:
1. Upstream server down
2. Proxy misconfiguration
3. Load balancer issues
**Solutions**:
- Usually temporary - retry later
- Check service status page
- Implement retry logic
---
### 503 Service Unavailable
```
HTTP 503 Service Unavailable
```
**Causes**:
1. Server overloaded
2. Maintenance mode
3. Capacity issues
**Solutions**:
```javascript
// Helper function
const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms))
// Retry with exponential backoff
async function fetchWithBackoff(url) {
const maxRetries = 5
for (let i = 0; i < maxRetries; i++) {
try {
const response = await fetch(url)
if (response.status === 503) {
await sleep(Math.pow(2, i) * 1000) // 1s, 2s, 4s, 8s, 16s
continue
}
return response
} catch (error) {
if (i === maxRetries - 1) throw error
await sleep(Math.pow(2, i) * 1000)
}
}
throw new Error('Max retries exceeded')
}
```
---
### 504 Gateway Timeout
```
HTTP 504 Gateway Timeout
```
**Causes**:
1. Upstream server too slow
2. Long-running operation
3. Network timeout
**Solutions**:
- Increase timeout settings
- Use async/webhook pattern for long operations
- Implement pagination for large responses
---
## Connection Errors
### ECONNREFUSED
```
Error: connect ECONNREFUSED 127.0.0.1:3000
```
**Causes**:
1. Server not running
2. Wrong port
3. Firewall blocking
**Diagnosis**:
```bash
# Check if port is listening
lsof -i :3000
netstat -an | grep 3000
curl -v http://localhost:3000
```
**Solutions**:
1. Start the server
2. Check port configuration
3. Check firewall rules
---
### ENOTFOUND
```
Error: getaddrinfo ENOTFOUND api.example.com
```
**Causes**:
1. Invalid hostname
2. DNS resolution failure
3. No internet connection
**Diagnosis**:
```bash
# Test DNS
nslookup api.example.com
dig api.example.com
ping api.example.com
```
**Solutions**:
1. Check URL spelling
2. Try different DNS (8.8.8.8)
3. Check internet connection
4. Check /etc/hosts file
---
### ETIMEDOUT
```
Error: connect ETIMEDOUT
```
**Causes**:
1. Server not responding
2. Firewall silently dropping
3. Network congestion
**Solutions**:
```javascript
// Increase timeout
const controller = new AbortController()
const timeoutId = setTimeout(() => controller.abort(), 30000)
try {
const response = await fetch(url, { signal: controller.signal })
clearTimeout(timeoutId)
return response
} catch (error) {
if (error.name === 'AbortError') {
throw new Error('Request timed out')
}
throw error
}
```
---
### ECONNRESET
```
Error: read ECONNRESET
```
**Causes**:
1. Server closed connection unexpectedly
2. Network interruption
3. Server crashed
**Solutions**:
```javascript
// Implement retry logic
async function fetchWithRetry(url, retries = 3) {
for (let i = 0; i < retries; i++) {
try {
return await fetch(url)
} catch (error) {
if (error.code === 'ECONNRESET' && i < retries - 1) {
await sleep(1000 * (i + 1))
continue
}
throw error
}
}
}
```
---
### SSL/TLS Errors
#### UNABLE_TO_VERIFY_LEAF_SIGNATURE
```
Error: unable to verify the first certificate
```
**Causes**:
1. Self-signed certificate
2. Missing intermediate certificate
3. Expired certificate
**Solutions**:
```javascript
// Development only - disable verification (NOT FOR PRODUCTION)
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'
// Better - add CA certificate
const https = require('https')
const agent = new https.Agent({
ca: fs.readFileSync('ca-cert.pem'),
})
fetch(url, { agent })
```
#### CERT_HAS_EXPIRED
```
Error: certificate has expired
```
**Solutions**:
1. Update server certificate
2. Check system time is correct
3. Update CA certificates: `update-ca-certificates`
---
## CORS Errors
### Access-Control-Allow-Origin
```
Access to fetch at 'https://api.example.com' from origin 'https://myapp.com'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present
```
**Causes**:
1. Server doesn't allow cross-origin requests
2. Missing CORS headers
3. Credentials mode mismatch
**Solutions (Server-side)**:
```javascript
// Express.js
const cors = require('cors')
app.use(cors({
origin: 'https://myapp.com', // Or '*' for all (not recommended)
credentials: true,
}))
// Manual headers
app.use((req, res, next) => {
res.header('Access-Control-Allow-Origin', 'https://myapp.com')
res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE')
res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization')
res.header('Access-Control-Allow-Credentials', 'true')
next()
})
```
**Solutions (Client-side workarounds)**:
```javascript
// Use proxy in development
// vite.config.js
export default {
server: {
proxy: {
'/api': {
target: 'https://api.example.com',
changeOrigin: true,
}
}
}
}
// Then fetch from /api instead
fetch('/api/endpoint')
```
---
### Preflight Request Failed
```
Response to preflight request doesn't pass access control check
```
**Causes**:
1. OPTIONS request not handled
2. Missing preflight headers
**Solutions**:
```javascript
// Handle OPTIONS request
app.options('*', cors()) // Express with cors
// Or manually
app.options('*', (req, res) => {
res.header('Access-Control-Allow-Origin', '*')
res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization')
res.sendStatus(200)
})
```
---
## JSON Parsing Errors
### Unexpected token < in JSON
```
SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
```
**Causes**:
1. Server returned HTML instead of JSON (error page, 404)
2. Wrong endpoint
3. Auth redirect
**Diagnosis**:
```javascript
const response = await fetch(url)
console.log('Status:', response.status)
console.log('Content-Type:', response.headers.get('content-type'))
const text = await response.text()
console.log('Body:', text.substring(0, 200))
```
**Solutions**:
```javascript
// Check response before parsing
const response = await fetch(url)
if (!response.ok) {
const text = await response.text()
throw new Error(`HTTP ${response.status}: ${text}`)
}
const contentType = response.headers.get('content-type')
if (!contentType?.includes('application/json')) {
throw new Error(`Expected JSON, got ${contentType}`)
}
return response.json()
```
---
### Unexpected end of JSON input
```
SyntaxError: Unexpected end of JSON input
```
**Causes**:
1. Empty response body
2. Truncated response
3. Network interruption
**Solutions**:
```javascript
// Check for empty response
const text = await response.text()
if (!text) {
return null // Or default value
}
return JSON.parse(text)
```
---
## Quick Reference Table
| Error | Category | Quick Fix |
|-------|----------|-----------|
| 400 Bad Request | Client | Check JSON format, Content-Type |
| 401 Unauthorized | Auth | Check token, refresh if expired |
| 403 Forbidden | Auth | Check permissions, rate limits |
| 404 Not Found | Client | Verify URL, check resource exists |
| 429 Too Many Requests | Rate Limit | Implement backoff, reduce requests |
| 500 Internal Server Error | Server | Retry, report to provider |
| 503 Service Unavailable | Server | Retry with exponential backoff |
| ECONNREFUSED | Connection | Start server, check port |
| ENOTFOUND | DNS | Check hostname, DNS settings |
| ETIMEDOUT | Timeout | Increase timeout, check network |
| CORS blocked | Browser | Add CORS headers server-side |
| Unexpected token < | Parse | Check response is JSON not HTML |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |