community-scripts/ProxmoxVED
1
0
Fork 0
mirror of https://github.com/community-scripts/ProxmoxVED.git synced 2026-02-25 05:57:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for all files in /misc

Browse Source
This commit is contained in:
Michel Roegl-Brunner
2025-10-10 11:18:59 +02:00
parent b006c4f74b
commit 960fddb9ee
19 changed files with 7095 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

424
docs/misc/error_handler.func/ERROR_HANDLER_FUNCTIONS_REFERENCE.md Normal file
View File

@@ -0,0 +1,424 @@
# error_handler.func Functions Reference
## Overview
This document provides a comprehensive alphabetical reference of all functions in `error_handler.func`, including parameters, dependencies, usage examples, and error handling.
## Function Categories
### Error Explanation Functions
#### `explain_exit_code()`
**Purpose**: Convert numeric exit codes to human-readable explanations
**Parameters**:
- `$1` - Exit code to explain
**Returns**: Human-readable error explanation string
**Side Effects**: None
**Dependencies**: None
**Environment Variables Used**: None
**Supported Exit Codes**:
- **Generic/Shell**: 1, 2, 126, 127, 128, 130, 137, 139, 143
- **Package Manager**: 100, 101, 255
- **Node.js**: 243, 245, 246, 247, 248, 249, 254
- **Python**: 210, 211, 212
- **PostgreSQL**: 231, 232, 233, 234
- **MySQL/MariaDB**: 241, 242, 243, 244
- **MongoDB**: 251, 252, 253, 254
- **Proxmox Custom**: 200, 203, 204, 205, 209, 210, 214, 215, 216, 217, 220, 222, 223, 231
**Usage Example**:
```bash
explanation=$(explain_exit_code 127)
echo "Error 127: $explanation"
# Output: Error 127: Command not found
```
**Error Code Examples**:
```bash
explain_exit_code 1 # "General error / Operation not permitted"
explain_exit_code 126 # "Command invoked cannot execute (permission problem?)"
explain_exit_code 127 # "Command not found"
explain_exit_code 130 # "Terminated by Ctrl+C (SIGINT)"
explain_exit_code 200 # "Custom: Failed to create lock file"
explain_exit_code 999 # "Unknown error"
```
### Error Handling Functions
#### `error_handler()`
**Purpose**: Main error handler triggered by ERR trap or manual call
**Parameters**:
- `$1` - Exit code (optional, defaults to $?)
- `$2` - Command that failed (optional, defaults to BASH_COMMAND)
**Returns**: None (exits with error code)
**Side Effects**:
- Displays detailed error information
- Logs error to debug file if enabled
- Shows silent log content if available
- Exits with original error code
**Dependencies**: `explain_exit_code()`
**Environment Variables Used**: `DEBUG_LOGFILE`, `SILENT_LOGFILE`
**Usage Example**:
```bash
# Automatic error handling via ERR trap
set -e
trap 'error_handler' ERR
# Manual error handling
error_handler 127 "command_not_found"
```
**Error Information Displayed**:
- Error message with color coding
- Line number where error occurred
- Exit code with explanation
- Command that failed
- Silent log content (last 20 lines)
- Debug log entry (if enabled)
### Signal Handling Functions
#### `on_interrupt()`
**Purpose**: Handle SIGINT (Ctrl+C) signals gracefully
**Parameters**: None
**Returns**: None (exits with code 130)
**Side Effects**:
- Displays interruption message
- Exits with SIGINT code (130)
**Dependencies**: None
**Environment Variables Used**: None
**Usage Example**:
```bash
# Set up interrupt handler
trap on_interrupt INT
# User presses Ctrl+C
# Handler displays: "Interrupted by user (SIGINT)"
# Script exits with code 130
```
#### `on_terminate()`
**Purpose**: Handle SIGTERM signals gracefully
**Parameters**: None
**Returns**: None (exits with code 143)
**Side Effects**:
- Displays termination message
- Exits with SIGTERM code (143)
**Dependencies**: None
**Environment Variables Used**: None
**Usage Example**:
```bash
# Set up termination handler
trap on_terminate TERM
# System sends SIGTERM
# Handler displays: "Terminated by signal (SIGTERM)"
# Script exits with code 143
```
### Cleanup Functions
#### `on_exit()`
**Purpose**: Handle script exit cleanup
**Parameters**: None
**Returns**: None (exits with original exit code)
**Side Effects**:
- Removes lock file if set
- Exits with original exit code
**Dependencies**: None
**Environment Variables Used**: `lockfile`
**Usage Example**:
```bash
# Set up exit handler
trap on_exit EXIT
# Set lock file
lockfile="/tmp/my_script.lock"
# Script exits normally or with error
# Handler removes lock file and exits
```
### Initialization Functions
#### `catch_errors()`
**Purpose**: Initialize error handling traps and strict mode
**Parameters**: None
**Returns**: None
**Side Effects**:
- Sets strict error handling mode
- Sets up error traps
- Sets up signal traps
- Sets up exit trap
**Dependencies**: None
**Environment Variables Used**: `STRICT_UNSET`
**Strict Mode Settings**:
- `-E`: Exit on command failure
- `-e`: Exit on any error
- `-o pipefail`: Exit on pipe failure
- `-u`: Exit on unset variables (if STRICT_UNSET=1)
**Trap Setup**:
- `ERR`: Calls `error_handler` on command failure
- `EXIT`: Calls `on_exit` on script exit
- `INT`: Calls `on_interrupt` on SIGINT
- `TERM`: Calls `on_terminate` on SIGTERM
**Usage Example**:
```bash
# Initialize error handling
catch_errors
# Script now has full error handling
# All errors will be caught and handled
```
## Function Call Hierarchy
### Error Handling Flow
```
Command Failure
├── ERR trap triggered
├── error_handler() called
│ ├── Get exit code
│ ├── Get command info
│ ├── Get line number
│ ├── explain_exit_code()
│ ├── Display error info
│ ├── Log to debug file
│ ├── Show silent log
│ └── Exit with error code
```
### Signal Handling Flow
```
Signal Received
├── Signal trap triggered
├── Appropriate handler called
│ ├── on_interrupt() for SIGINT
│ ├── on_terminate() for SIGTERM
│ └── on_exit() for EXIT
└── Exit with signal code
```
### Initialization Flow
```
catch_errors()
├── Set strict mode
│ ├── -E (exit on failure)
│ ├── -e (exit on error)
│ ├── -o pipefail (pipe failure)
│ └── -u (unset variables, if enabled)
└── Set up traps
├── ERR → error_handler
├── EXIT → on_exit
├── INT → on_interrupt
└── TERM → on_terminate
```
## Error Code Reference
### Generic/Shell Errors
| Code | Description |
|------|-------------|
| 1 | General error / Operation not permitted |
| 2 | Misuse of shell builtins (e.g. 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
| Code | Description |
|------|-------------|
| 100 | APT: Package manager error (broken packages / dependency problems) |
| 101 | APT: Configuration error (bad sources.list, malformed config) |
| 255 | DPKG: Fatal internal error |
### Node.js Errors
| Code | Description |
|------|-------------|
| 243 | Node.js: Out of memory (JavaScript heap out of memory) |
| 245 | Node.js: Invalid command-line option |
| 246 | Node.js: Internal JavaScript Parse Error |
| 247 | Node.js: Fatal internal error |
| 248 | Node.js: Invalid C++ addon / N-API failure |
| 249 | Node.js: Inspector error |
| 254 | npm/pnpm/yarn: Unknown fatal error |
### Python Errors
| Code | Description |
|------|-------------|
| 210 | Python: Virtualenv / uv environment missing or broken |
| 211 | Python: Dependency resolution failed |
| 212 | Python: Installation aborted (permissions or EXTERNALLY-MANAGED) |
### Database Errors
| Code | Description |
|------|-------------|
| 231 | PostgreSQL: Connection failed (server not running / wrong socket) |
| 232 | PostgreSQL: Authentication failed (bad user/password) |
| 233 | PostgreSQL: Database does not exist |
| 234 | PostgreSQL: Fatal error in query / syntax |
| 241 | MySQL/MariaDB: Connection failed (server not running / wrong socket) |
| 242 | MySQL/MariaDB: Authentication failed (bad user/password) |
| 243 | MySQL/MariaDB: Database does not exist |
| 244 | MySQL/MariaDB: Fatal error in query / syntax |
| 251 | MongoDB: Connection failed (server not running) |
| 252 | MongoDB: Authentication failed (bad user/password) |
| 253 | MongoDB: Database not found |
| 254 | MongoDB: Fatal query error |
### Proxmox Custom Errors
| Code | Description |
|------|-------------|
| 200 | Custom: Failed to create lock file |
| 203 | Custom: Missing CTID variable |
| 204 | Custom: Missing PCT_OSTYPE variable |
| 205 | Custom: Invalid CTID (<100) |
| 209 | Custom: Container creation failed |
| 210 | Custom: Cluster not quorate |
| 214 | Custom: Not enough storage space |
| 215 | Custom: Container ID not listed |
| 216 | Custom: RootFS entry missing in config |
| 217 | Custom: Storage does not support rootdir |
| 220 | Custom: Unable to resolve template path |
| 222 | Custom: Template download failed after 3 attempts |
| 223 | Custom: Template not available after download |
| 231 | Custom: LXC stack upgrade/retry failed |
## Environment Variable Dependencies
### Required Variables
- **`lockfile`**: Lock file path for cleanup (set by calling script)
### Optional 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
- **`exit_code`**: Current exit code
- **`command`**: Failed command
- **`line_number`**: Line number where error occurred
- **`explanation`**: Error explanation text
## Error Handling Patterns
### Automatic Error Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Initialize error handling
catch_errors
# All commands are now monitored
# Errors will be automatically caught and handled
```
### Manual Error Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Manual error handling
if ! command -v required_tool >/dev/null 2>&1; then
error_handler 127 "required_tool not found"
fi
```
### Custom Error Codes
```bash
#!/usr/bin/env bash
source error_handler.func
# Use custom error codes
if [[ ! -f /required/file ]]; then
echo "Error: Required file missing"
exit 200 # Custom error code
fi
```
### Signal Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Set up signal handling
trap on_interrupt INT
trap on_terminate TERM
trap on_exit EXIT
# Script handles signals gracefully
```
## Integration Examples
### With core.func
```bash
#!/usr/bin/env bash
source core.func
source error_handler.func
# Silent execution uses error_handler for explanations
silent apt-get install -y package
# If command fails, error_handler provides explanation
```
### With build.func
```bash
#!/usr/bin/env bash
source core.func
source error_handler.func
source build.func
# Container creation with error handling
# Errors are caught and explained
```
### With tools.func
```bash
#!/usr/bin/env bash
source core.func
source error_handler.func
source tools.func
# Tool operations with error handling
# All errors are properly handled and explained
```
## Best Practices
### Error Handling Setup
1. Source error_handler.func early in script
2. Call catch_errors() to initialize traps
3. Use appropriate 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
### Custom Error Codes
1. Use Proxmox custom error codes (200-231) for container/VM errors
2. Use standard error codes for common operations
3. Document custom error codes in script comments
4. Provide clear error messages for custom codes