ProxmoxVED/docs/misc/error_handler.func

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

Visual execution flows showing error handling processes and signal management.

📚 ERROR_HANDLER_FUNCTIONS_REFERENCE.md

Complete alphabetical reference of all functions with parameters, dependencies, and usage details.

💡 ERROR_HANDLER_USAGE_EXAMPLES.md

Practical examples showing how to use error handling functions and common patterns.

🔗 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

#!/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

#!/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

#!/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:

export DEBUG_LOGFILE="/tmp/debug.log"
source error_handler.func
catch_errors

Error Code Testing

Test error explanations:

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 utilities and silent execution
• build.func - Container creation with error handling
• tools.func - Extended utilities with error handling
• 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.