error-handling git:20261014.522e28aA

Immutable. This exact content never changes and is served at /api/v1/blob/bb7b320865d6ff65.

---
name: error-handling
description: "Writes robust Python and TypeScript error handling: timeouts, retries, graceful shutdown. Use when writing code that calls external services, files or the network."
---

# Robust Error Handling (Python / TypeScript)

When writing or refactoring code in Python or TypeScript, especially code that deals with I/O, network requests, or long-running processes, you MUST prioritize robustness and apply the following patterns:

## 1. Always Clean Up (try/finally)
Ensure that resources (files, network connections, sessions, clients) are always closed properly.
- **Python**: Use `try/finally` blocks or context managers (`with`).
- **TypeScript**: Use `try/finally` blocks.

## 2. Handle Specific Errors
Do not blindly catch generic exceptions unless it's a top-level fail-safe.
- **Python**: Catch `FileNotFoundError`, `ConnectionError`, `TimeoutError`, etc., before `Exception`.
- **TypeScript**: Check the `error.message` or `error.code` (e.g., `ENOENT`, `ECONNREFUSED`) to handle known failure states gracefully.

## 3. Set Appropriate Timeouts
Never make synchronous or asynchronous calls to external services or long-running processes without setting a timeout.
- Use timeout arguments in APIs when available.
- If not available, use `asyncio.wait_for` (Python) or `Promise.race` with a timeout promise (TypeScript).

## 4. Graceful Shutdown
Long-running scripts should handle interruption signals (e.g., `SIGINT`) to clean up before exiting.
- **Python**: Use the `signal` module to catch `signal.SIGINT` and trigger cleanup tasks.
- **TypeScript**: Use `process.on("SIGINT", ...)` to await cleanup before `process.exit(0)`.

## 5. Log Errors
Always capture and log error details (and stack traces when necessary) for debugging. Don't swallow errors silently.