# Common Failure Patterns

> |

- **Type:** Skill
- **Install:** `agentstack add skill-aeyeops-aeo-skill-marketplace-common-failure-patterns`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AeyeOps](https://agentstack.voostack.com/s/aeyeops)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AeyeOps](https://github.com/AeyeOps)
- **Source:** https://github.com/AeyeOps/aeo-skill-marketplace/tree/main/aeo-troubleshooting/skills/common-failure-patterns

## Install

```sh
agentstack add skill-aeyeops-aeo-skill-marketplace-common-failure-patterns
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Common Failure Patterns

## Dependency Conflicts

### Version Mismatch
```markdown
Symptoms:
- ImportError or ModuleNotFoundError at runtime
- "No matching distribution found" during install
- Tests pass locally but fail in CI
- AttributeError on functions that "should exist"

Diagnosis:
  pip freeze | grep     # What's actually installed?
  pip show              # Version + dependencies
  pip check                      # Dependency compatibility check
  npm ls                # Node dependency tree
  npm ls --all 2>&1 | grep ERR   # Find conflicts

Common causes:
- Lock file not committed (pip.lock, yarn.lock, package-lock.json)
- Different Python/Node version between local and CI
- Transitive dependency updated with breaking change
- Multiple packages requiring conflicting versions

Fixes:
- Pin exact versions in requirements.txt / package.json
- Use lock files and commit them to version control
- Use virtual environments to isolate project dependencies
- Run pip install --upgrade --force-reinstall 
- For Node: delete node_modules and reinstall
```

### Diamond Dependency Problem
```markdown
Symptoms:
- "Conflicting dependencies" during installation
- Package A requires X>=2.0 but Package B requires X           # Where is it found?
  echo $PATH                # What's in PATH?
  type             # Is it alias, function, or binary?
  env | grep PATH           # Full PATH variable
  ls -la $(which ) # Symlink target

Common causes:
- Tool installed in user directory but PATH has system directory first
- Shell profile (.bashrc, .zshrc) not sourced in this session
- Different shell (bash vs zsh) with different profiles
- Virtual environment not activated
- PATH modified by a tool installer without restarting shell

Fixes:
- Add the correct directory to PATH in your shell profile
- Source the profile: source ~/.bashrc or source ~/.zshrc
- Use absolute paths as a temporary fix
- Check for conflicting PATH entries (earlier entries win)
```

### Permission Errors
```markdown
Symptoms:
- "Permission denied" on file operations
- "EACCES" (Node.js), PermissionError (Python)
- Works as root but not as regular user
- Works locally but fails in container/CI

Diagnosis:
  ls -la                # Check owner and permissions
  stat                  # Detailed file attributes
  id                          # Current user and groups
  namei -l              # Permissions on entire path chain
  getfacl               # ACL permissions (if applicable)

Common causes:
- File created by root or different user
- Directory missing execute permission (can't traverse)
- Mounted volume with restrictive permissions
- SELinux or AppArmor blocking access
- umask setting creating restrictive default permissions

Fixes:
  chmod 644             # Read/write for owner, read for others
  chmod 755        # Execute needed to enter directories
  chown user:group      # Change ownership
  # In Docker: run as non-root user matching host UID
  # In CI: check runner user and directory permissions
```

### Environment Variable Issues
```markdown
Symptoms:
- KeyError or "environment variable not set"
- Application uses wrong configuration (staging vs production)
- Works in terminal but fails as a service/cron job

Diagnosis:
  env | grep             # Is it set?
  printenv               # Value of specific variable
  # In Python: os.environ.get('VAR', 'default')
  # In Node: process.env.VAR

Common causes:
- Variable set in shell but not exported (export VAR=value)
- Variable set in .bashrc but process started differently
- .env file not loaded (missing dotenv setup)
- Docker container missing --env or --env-file
- CI/CD secrets not configured for this environment

Fixes:
- Use .env files with a loader (python-dotenv, dotenv for Node)
- Set in systemd service file, Docker Compose, or CI config
- Fail fast with clear error message if required var is missing
- Document required environment variables in README or .env.example
```

## Network Errors

### CORS Errors
```markdown
Symptoms:
- "Access-Control-Allow-Origin" error in browser console
- API works from curl/Postman but fails from browser
- Preflight OPTIONS request returns 403 or missing headers
- "has been blocked by CORS policy"

This is a BROWSER-ONLY issue — the server must set headers.

Diagnosis:
  # Check response headers
  curl -I -X OPTIONS https://api.example.com/endpoint \
    -H "Origin: https://yoursite.com" \
    -H "Access-Control-Request-Method: POST"

Required server response headers:
  Access-Control-Allow-Origin: https://yoursite.com  (or * for public APIs)
  Access-Control-Allow-Methods: GET, POST, PUT, DELETE
  Access-Control-Allow-Headers: Content-Type, Authorization
  Access-Control-Allow-Credentials: true  (if sending cookies)

Common causes:
- Backend missing CORS middleware
- Allowed origins list doesn't include the frontend URL
- Credentials mode enabled but origin is wildcard (*)
- Preflight (OPTIONS) request not handled by server
- Reverse proxy stripping CORS headers

Fixes:
- Add CORS middleware to backend (flask-cors, cors npm package)
- Configure allowed origins explicitly (avoid * in production)
- Ensure OPTIONS requests reach your CORS handler
- Check proxy/CDN configuration isn't stripping headers
```

### DNS Failures
```markdown
Symptoms:
- "Could not resolve hostname"
- "getaddrinfo ENOTFOUND"
- "Name or service not known"
- Works with IP address but not hostname

Diagnosis:
  dig               # DNS resolution details
  nslookup          # Simple DNS lookup
  host              # Another DNS query tool
  cat /etc/resolv.conf        # DNS server configuration
  ping              # Basic connectivity test

Common causes:
- DNS server is down or unreachable
- Hostname is misspelled
- DNS record doesn't exist or hasn't propagated
- /etc/resolv.conf points to wrong DNS server
- Docker container using wrong DNS configuration
- VPN or firewall blocking DNS queries

Fixes:
- Verify hostname spelling
- Try alternative DNS (8.8.8.8, 1.1.1.1)
- Check DNS record exists: dig  @8.8.8.8
- In Docker: set --dns flag or configure daemon DNS
- Wait for DNS propagation (TTL, typically minutes to hours)
```

### Timeout Errors
```markdown
Symptoms:
- "Connection timed out" (can't establish connection)
- "Read timed out" (connected but no response)
- "Gateway Timeout" (502/504 from proxy)
- Request hangs for a long time then fails

Diagnosis:
  # Test basic connectivity
  telnet  
  nc -zv  

  # Measure response time
  curl -o /dev/null -w "Total: %{time_total}s\n" 

  # Trace network path
  traceroute 

Common causes:
- Server is overloaded or down
- Firewall blocking the port
- Client timeout set too low for the operation
- Network latency between client and server
- DNS resolution is slow
- Connection pool exhausted
- Backend processing takes too long (slow query, heavy computation)

Fixes:
- Increase timeout for legitimately slow operations
- Add connection pooling and reuse
- Implement retry with exponential backoff
- Add circuit breaker to prevent cascade failures
- Optimize slow server-side operations
- Check firewall rules (security groups, iptables)
```

## Async and Concurrency Bugs

### Race Conditions
```markdown
Symptoms:
- Bug appears intermittently under load
- Result depends on timing or order of operations
- Works single-threaded but fails multi-threaded
- "Lost updates" — data written then overwritten

Classic example:
  Thread A: read balance (100)
  Thread B: read balance (100)
  Thread A: write balance (100 + 50 = 150)
  Thread B: write balance (100 - 30 = 70)   ← Thread A's write is lost!

Diagnosis:
- Add timestamps to logs and correlate concurrent operations
- Increase concurrency to make the race more likely
- Use thread-sanitizer or race-condition detection tools
- Look for shared mutable state accessed without synchronization

Fixes:
- Use locks/mutexes for shared state: with lock: ...
- Use atomic operations where available
- Use database transactions with appropriate isolation level
- Apply optimistic locking (version column, compare-and-swap)
- Redesign to avoid shared mutable state (message passing, queues)
```

### Deadlocks
```markdown
Symptoms:
- Application freezes/hangs completely
- No error message — just stops responding
- CPU is idle but application makes no progress
- Threads waiting on each other

Classic pattern:
  Thread A: locks Resource 1, waits for Resource 2
  Thread B: locks Resource 2, waits for Resource 1
  → Neither can proceed

Diagnosis:
- Thread dump: kill -3  (Java), faulthandler (Python)
- Database: SELECT * FROM pg_locks WHERE NOT granted;
- Look for circular dependencies in lock acquisition

Fixes:
- Always acquire locks in a consistent global order
- Use timeouts on lock acquisition
- Use try-lock with fallback
- Reduce lock scope (hold locks for minimum time)
- Use lock-free data structures where possible
- In databases: keep transactions short, access tables in consistent order
```

### Unhandled Promise/Async Errors
```markdown
Symptoms:
- "UnhandledPromiseRejection" (Node.js)
- Silent failures (async code fails but nothing logs it)
- "RuntimeWarning: coroutine was never awaited" (Python)
- Function returns before async work completes

Common causes:
- Missing await keyword
- Missing .catch() on Promise chain
- async function called without await (fire-and-forget)
- Error thrown inside callback but not propagated

Fixes:
  # JavaScript
  ✗ fetchData()                    # Missing await
  ✓ await fetchData()
  ✓ fetchData().catch(handleError)

  # Python
  ✗ asyncio.create_task(work())    # Error lost if work() fails
  ✓ task = asyncio.create_task(work())
    task.add_done_callback(handle_error)
```

## Memory Leaks

### Symptoms
```markdown
- Memory usage grows steadily over time
- Application gets slower over time
- OOM (Out of Memory) kills after hours/days of running
- Garbage collector runs more frequently
```

### Common Causes

```markdown
Event listeners not removed:
  ✗ element.addEventListener('click', handler)  # Never removed
  ✓ Cleanup: element.removeEventListener('click', handler)

Growing collections:
  ✗ cache = {}  # Keys added, never evicted
  ✓ Use LRU cache with max size

Closures holding references:
  ✗ Large objects referenced by closures that outlive their usefulness
  ✓ Set references to null when no longer needed

Circular references (in non-GC languages):
  ✗ A references B, B references A → neither freed
  ✓ Use weak references or explicit cleanup

Database connections not closed:
  ✗ conn = db.connect()  # Never closed
  ✓ with db.connect() as conn:  # Auto-cleanup via context manager
```

### Diagnosis

```markdown
Python:
  tracemalloc.start()          # Track memory allocations
  objgraph.show_most_common_types()  # Find leaked objects
  gc.get_referrers(obj)        # What holds a reference?

Node.js:
  --inspect + Chrome DevTools → Memory tab → Heap snapshots
  Compare two snapshots to find growing objects

General:
  Monitor RSS (Resident Set Size) over time
  If it grows without bound → leak
  If it grows then levels off → just needs more memory
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AeyeOps](https://github.com/AeyeOps)
- **Source:** [AeyeOps/aeo-skill-marketplace](https://github.com/AeyeOps/aeo-skill-marketplace)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aeyeops-aeo-skill-marketplace-common-failure-patterns
- Seller: https://agentstack.voostack.com/s/aeyeops
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.