ProxmoxVED/docs/misc/error_handler.func/README.md

# error_handler.func Documentation

## Overview

The `error_handler.func` file provides comprehensive error handling and signal management for Proxmox Community Scripts. It offers detailed error code explanations, graceful error recovery, and proper cleanup mechanisms.

## Purpose and Use Cases

- **Error Code Explanation**: Provides human-readable explanations for exit codes
- **Signal Handling**: Manages SIGINT, SIGTERM, and other signals gracefully
- **Error Recovery**: Implements proper cleanup and error reporting
- **Debug Logging**: Records error information for troubleshooting
- **Silent Execution Support**: Integrates with core.func silent execution

## Quick Reference

### Key Function Groups
- **Error Explanation**: `explain_exit_code()` - Convert exit codes to human-readable messages
- **Error Handling**: `error_handler()` - Main error handler with detailed reporting
- **Signal Handlers**: `on_interrupt()`, `on_terminate()` - Graceful signal handling
- **Cleanup**: `on_exit()` - Cleanup on script exit
- **Trap Setup**: `catch_errors()` - Initialize error handling traps

### Dependencies
- **External**: None (pure Bash implementation)
- **Internal**: Uses color variables from core.func

### Integration Points
- Used by: All scripts via core.func silent execution
- Uses: Color variables from core.func
- Provides: Error explanations for core.func silent function

## Documentation Files

### 📊 [ERROR_HANDLER_FLOWCHART.md](./ERROR_HANDLER_FLOWCHART.md)
Visual execution flows showing error handling processes and signal management.

### 📚 [ERROR_HANDLER_FUNCTIONS_REFERENCE.md](./ERROR_HANDLER_FUNCTIONS_REFERENCE.md)
Complete alphabetical reference of all functions with parameters, dependencies, and usage details.

### 💡 [ERROR_HANDLER_USAGE_EXAMPLES.md](./ERROR_HANDLER_USAGE_EXAMPLES.md)
Practical examples showing how to use error handling functions and common patterns.

### 🔗 [ERROR_HANDLER_INTEGRATION.md](./ERROR_HANDLER_INTEGRATION.md)
How error_handler.func integrates with other components and provides error handling services.

## Key Features

### Error Code Categories
- **Generic/Shell Errors**: Exit codes 1, 2, 126, 127, 128, 130, 137, 139, 143
- **Package Manager Errors**: APT/DPKG errors (100, 101, 255)
- **Node.js Errors**: JavaScript runtime errors (243-249, 254)
- **Python Errors**: Python environment and dependency errors (210-212)
- **Database Errors**: PostgreSQL, MySQL, MongoDB errors (231-254)
- **Proxmox Custom Errors**: Container and VM specific errors (200-231)

### Signal Handling
- **SIGINT (Ctrl+C)**: Graceful interruption handling
- **SIGTERM**: Graceful termination handling
- **EXIT**: Cleanup on script exit
- **ERR**: Error trap for command failures

### Error Reporting
- **Detailed Messages**: Human-readable error explanations
- **Context Information**: Line numbers, commands, timestamps
- **Log Integration**: Silent log file integration
- **Debug Logging**: Optional debug log file support

## Common Usage Patterns

### Basic Error Handling Setup
```bash
#!/usr/bin/env bash
# Basic error handling setup

source error_handler.func

# Initialize error handling
catch_errors

# Your script code here
# Errors will be automatically handled
```

### Manual Error Explanation
```bash
#!/usr/bin/env bash
source error_handler.func

# Get error explanation
explanation=$(explain_exit_code 127)
echo "Error 127: $explanation"
# Output: Error 127: Command not found
```

### Custom Error Handling
```bash
#!/usr/bin/env bash
source error_handler.func

# Custom error handling
if ! command -v required_tool >/dev/null 2>&1; then
    echo "Error: required_tool not found"
    exit 127
fi
```

## Environment Variables

### Debug Variables
- `DEBUG_LOGFILE`: Path to debug log file for error logging
- `SILENT_LOGFILE`: Path to silent execution log file
- `STRICT_UNSET`: Enable strict unset variable checking (0/1)

### Internal Variables
- `lockfile`: Lock file path for cleanup (set by calling script)
- `exit_code`: Current exit code
- `command`: Failed command
- `line_number`: Line number where error occurred

## Error Categories

### Generic/Shell Errors
- **1**: General error / Operation not permitted
- **2**: Misuse of shell builtins (syntax error)
- **126**: Command invoked cannot execute (permission problem)
- **127**: Command not found
- **128**: Invalid argument to exit
- **130**: Terminated by Ctrl+C (SIGINT)
- **137**: Killed (SIGKILL / Out of memory)
- **139**: Segmentation fault (core dumped)
- **143**: Terminated (SIGTERM)

### Package Manager Errors
- **100**: APT package manager error (broken packages)
- **101**: APT configuration error (bad sources.list)
- **255**: DPKG fatal internal error

### Node.js Errors
- **243**: JavaScript heap out of memory
- **245**: Invalid command-line option
- **246**: Internal JavaScript parse error
- **247**: Fatal internal error
- **248**: Invalid C++ addon / N-API failure
- **249**: Inspector error
- **254**: npm/pnpm/yarn unknown fatal error

### Python Errors
- **210**: Virtualenv/uv environment missing or broken
- **211**: Dependency resolution failed
- **212**: Installation aborted (permissions or EXTERNALLY-MANAGED)

### Database Errors
- **PostgreSQL (231-234)**: Connection, authentication, database, query errors
- **MySQL/MariaDB (241-244)**: Connection, authentication, database, query errors
- **MongoDB (251-254)**: Connection, authentication, database, query errors

### Proxmox Custom Errors
- **200**: Failed to create lock file
- **203**: Missing CTID variable
- **204**: Missing PCT_OSTYPE variable
- **205**: Invalid CTID (<100)
- **209**: Container creation failed
- **210**: Cluster not quorate
- **214**: Not enough storage space
- **215**: Container ID not listed
- **216**: RootFS entry missing in config
- **217**: Storage does not support rootdir
- **220**: Unable to resolve template path
- **222**: Template download failed after 3 attempts
- **223**: Template not available after download
- **231**: LXC stack upgrade/retry failed

## Best Practices

### Error Handling Setup
1. Source error_handler.func early in script
2. Call catch_errors() to initialize traps
3. Use proper exit codes for different error types
4. Provide meaningful error messages

### Signal Handling
1. Always set up signal traps
2. Provide graceful cleanup on interruption
3. Use appropriate exit codes for signals
4. Clean up temporary files and processes

### Error Reporting
1. Use explain_exit_code() for user-friendly messages
2. Log errors to debug files when needed
3. Provide context information (line numbers, commands)
4. Integrate with silent execution logging

## Troubleshooting

### Common Issues
1. **Missing Error Handler**: Ensure error_handler.func is sourced
2. **Trap Not Set**: Call catch_errors() to initialize traps
3. **Color Variables**: Ensure core.func is sourced for colors
4. **Lock Files**: Clean up lock files in on_exit()

### Debug Mode
Enable debug logging for detailed error information:
```bash
export DEBUG_LOGFILE="/tmp/debug.log"
source error_handler.func
catch_errors
```

### Error Code Testing
Test error explanations:
```bash
source error_handler.func
for code in 1 2 126 127 128 130 137 139 143; do
    echo "Code $code: $(explain_exit_code $code)"
done
```

## Related Documentation

- [core.func](../core.func/) - Core utilities and silent execution
- [build.func](../build.func/) - Container creation with error handling
- [tools.func](../tools.func/) - Extended utilities with error handling
- [api.func](../api.func/) - API operations with error handling

---

*This documentation covers the error_handler.func file which provides comprehensive error handling for all Proxmox Community Scripts.*