Exit Codes Reference

Understanding Exit Codes

Exit codes provide detailed information about why a script failed. Each code maps to a specific error condition, making troubleshooting faster and more precise.

Exit code 0 always indicates success. Non-zero codes indicate various types of failures.

Quick Reference Chart

Exit Code Range	Category	Typical Issue
1-2, 126-143	Shell/System	Permissions, signals, missing commands
100-102	Package Manager	APT/DPKG errors, broken packages
103-125	Script Validation	Environment checks, prerequisites
160-162	Python/pip	Virtual environments, dependencies
170-193	Databases	Connection, authentication, query errors
200-209	Container Creation	CTID, password, configuration
210-217	Storage/Cluster	Disk space, quorum, storage type
218-225	Templates	Download, corruption, availability
231-238	Tools/Addons	Tool-specific errors
243-249	Node.js/npm	Runtime errors, memory issues
250-254	Application	Download, extraction, migration

Generic Shell Errors (1-2, 126-143)

Standard Unix/Linux exit codes used across all scripts.

# Exit Code 1 - General error / Operation not permitted
# Cause: Permission denied, general failure
# Solution: Check user permissions, run as root if needed

# Exit Code 2 - Misuse of shell builtins
# Cause: Syntax error in script
# Solution: Review script syntax, check bash version

Complete Shell Error Reference

Code	Description	Common Causes	Solutions
1	General error / Operation not permitted	Permission denied, general failure	Check user permissions, run as root if needed
2	Misuse of shell builtins	Syntax error in script	Review script syntax, check bash version
126	Command cannot execute	Permission problem, not executable	`chmod +x script.sh` or check file permissions
127	Command not found	Missing binary, wrong PATH	Install required package, check PATH variable
128	Invalid argument to exit	Invalid exit code passed	Use exit codes 0-255 only
130	Terminated by Ctrl+C (SIGINT)	User interrupted script	Expected behavior, no action needed
137	Killed (SIGKILL)	Out of memory, forced termination	Check memory usage, increase RAM allocation
139	Segmentation fault	Memory access violation, corrupted binary	Reinstall package, check system stability
143	Terminated (SIGTERM)	Graceful shutdown signal	Expected during container stops

Package Manager Errors (100-102, 255)

APT, DPKG, and package installation errors.

Exit Code 100 - APT Package Manager Error

Common Causes:

Broken packages
Dependency conflicts
Failed installations

Solutions:

# Fix broken packages
apt --fix-broken install

# Reconfigure packages
dpkg --configure -a

# Update and retry
apt update
apt upgrade

Exit Code 101 - APT Configuration Error

Common Causes:

Malformed sources.list
Bad repository configuration
Invalid GPG keys

Solutions:

# Check sources.list
cat /etc/apt/sources.list
cat /etc/apt/sources.list.d/*.list

# Fix and update
apt update

Exit Code 102 - APT Lock Held

Common Causes:

Another apt/dpkg process running
Stale lock files

Solutions:

# Check running processes
ps aux | grep -E 'apt|dpkg'

# If safe to remove locks:
rm /var/lib/dpkg/lock-frontend
rm /var/lib/dpkg/lock
dpkg --configure -a

Only remove lock files if no package manager processes are running.

Exit Code 255 - DPKG Fatal Internal Error

Common Causes:

Corrupted package database
System inconsistency

Solutions:

# Reconfigure all packages
dpkg --configure -a

# If needed, restore from backup
# Check /var/backups/dpkg.status.*

Script Validation Errors (103-125)

Environment checks and prerequisite validation.

Validation Error Codes

Code	Description	Solution
103	Shell is not Bash	Use bash to run the script
104	Not running as root	Run with sudo or as root user
105	Proxmox VE version not supported	Upgrade Proxmox VE
106	Architecture not supported (ARM/PiMox)	Use x86_64 architecture
109	No available container ID after max attempts	Manually specify CTID
116	Default bridge vmbr0 not found	Configure network bridge
117	Container did not reach running state	Check container logs
118	No IP assigned to container	Check DHCP/network config
119	No valid storage for rootdir	Configure compatible storage
122	No internet connectivity	Check network and routing

Container Creation Errors (200-209)

Errors during LXC container creation.

Exit Code 205 - Invalid CTID (<100)

Problem: Container ID is below the minimum allowed value.Solution: Use CTID ≥ 100. Container IDs 1-99 are reserved for Proxmox system use.

Exit Code 206 - CTID Already in Use

Problem: A container or VM with this ID already exists.Solutions:

# Check existing containers
pct list

# Check for ghost containers
ls /etc/pve/lxc/

# Use a different CTID

If a container appears in /etc/pve/lxc/ but not in pct list, manually remove the config file.

Exit Code 207 - Password Contains Special Characters

Problem: Password validation failed due to unescaped special characters.Problematic Characters: Special characters at start/end: -, /, \, *, !, @Solution: Use alphanumeric passwords or avoid leading/trailing special characters.

Exit Code 208 - Invalid Configuration

Common Issues:

DNS format: .home instead of home (remove leading dot)
MAC format: AA-BB-CC instead of AA:BB:CC (use colons)
Invalid IP address format

Solution: Verify all configuration parameters follow correct format.

Exit Code 209 - Container Creation Failed

Problem: General container creation failure.Solutions:

# Check detailed logs
tail -n 50 /tmp/pct_create_*.log

# Verify template
pveam list local

# Check storage
pvesm status

Storage & Cluster Errors (210-217)

Exit Code 210 - Cluster Not Quorate

Problem: Cluster doesn’t have enough nodes online.Solutions:

# Check cluster status
pvecm status

# For single-node testing (temporary)
pvecm expected 1

Exit Code 214 - Not Enough Storage Space

Solutions:

# Check storage
pvesm status
df -h

# Free up space
# - Remove old backups
# - Remove unused templates
# - Clean logs

Exit Code 217 - Storage Does Not Support Rootdir

Problem: Selected storage type doesn’t support LXC containers.Incompatible Storage:

iscsidirect (VMs only)
cephfs (use RBD instead)
pbs (backups only)

Compatible Storage:

dir, zfspool, lvm-thin, rbd

Template Errors (218-225)

Exit Code 218 - Template Corrupted or Incomplete

Common Causes:

Download interrupted
File size < 1MB
Invalid archive format

Solutions:

# Remove corrupted template
rm /var/lib/vz/template/cache/<template>

# Re-download
pveam update
pveam download local <template>

Exit Code 222 - Template Download Failed

Problem: Template download failed after 3 attempts.Solutions:

# Check connectivity
ping download.proxmox.com

# Verify storage
pvesm status
df -h

# Update and retry
pveam update

Exit Code 225 - No Template Available

Problem: Template not available for specified OS/version.Solutions:

# Update template list
pveam update

# Check available templates
pveam available --section system

Database Errors

# Exit Code 170 - Connection failed
systemctl status postgresql
systemctl start postgresql

# Exit Code 171 - Authentication failed
# Check pg_hba.conf and credentials

# Exit Code 172 - Database does not exist
CREATE DATABASE dbname;

# Exit Code 173 - Fatal error in query
# Review SQL syntax and constraints

Node.js/npm Errors (243-249)

Exit Code 243 - Out of Memory

Problem: JavaScript heap exhausted.Solutions:

# Increase memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

# Allocate more RAM to container
pct set <CTID> -memory 4096

Exit Code 247 - Fatal Internal Error

Solutions:

# Update Node.js
# Check for known bugs in Node.js version
# Review application logs

Exit Code 249 - npm/pnpm/yarn Fatal Error

Solutions:

# Clear cache
npm cache clean --force

# Reinstall package manager
npm install -g npm@latest

Python/pip Errors (160-162)

Exit Code 160 - Virtualenv Missing or Broken

Solutions:

# Recreate virtualenv
python3 -m venv venv
source venv/bin/activate

Exit Code 162 - Installation Aborted

Problem: EXTERNALLY-MANAGED or permission denied.Solutions:

# Use virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install <package>

# Or use --break-system-packages (with caution)
pip install --break-system-packages <package>

Application Errors (250-254)

Code	Description	Common Solution
250	Download failed or version not determined	Check network, verify URL
251	File extraction failed	Verify archive integrity
252	Required file or resource not found	Check installation path
253	Data migration required	Follow migration guide
254	User declined prompt or timeout	Review and accept prompts

Troubleshooting Tips

Finding Error Details

# View creation logs
tail -n 50 /tmp/pct_create_*.log

# View installation logs
tail -n 50 /tmp/install-*.log

# View persistent logs (if debug mode enabled)
tail -f /var/log/community-scripts/*.log

Common Patterns

Exit 0 with error message: Configuration validation failed (check DNS, MAC, password format)Exit 206 but container not visible: Ghost container state - check /etc/pve/lxc/ manuallyExit 209 generic error: Check /tmp/pct_create_*.log for specific pct create failure reasonExit 218 or 222: Template issues - delete and re-download template

Getting Started

Core Concepts

Using Scripts

Configuration

Guides

Troubleshooting

Understanding Exit Codes

Quick Reference Chart

Generic Shell Errors (1-2, 126-143)

Package Manager Errors (100-102, 255)

Script Validation Errors (103-125)

Container Creation Errors (200-209)

Storage & Cluster Errors (210-217)

Template Errors (218-225)

Database Errors

Node.js/npm Errors (243-249)

Python/pip Errors (160-162)

Application Errors (250-254)

Troubleshooting Tips

Finding Error Details

Common Patterns

See Also

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Using Scripts

Configuration

Guides

Troubleshooting

​Understanding Exit Codes

​Quick Reference Chart

​Generic Shell Errors (1-2, 126-143)

​Package Manager Errors (100-102, 255)

​Script Validation Errors (103-125)

​Container Creation Errors (200-209)

​Storage & Cluster Errors (210-217)

​Template Errors (218-225)

​Database Errors

​Node.js/npm Errors (243-249)

​Python/pip Errors (160-162)

​Application Errors (250-254)

​Troubleshooting Tips

​Finding Error Details

​Common Patterns

​See Also

Build docs developers (and LLMs) love

Understanding Exit Codes

Quick Reference Chart

Generic Shell Errors (1-2, 126-143)

Package Manager Errors (100-102, 255)

Script Validation Errors (103-125)

Container Creation Errors (200-209)

Storage & Cluster Errors (210-217)

Template Errors (218-225)

Database Errors

Node.js/npm Errors (243-249)

Python/pip Errors (160-162)

Application Errors (250-254)

Troubleshooting Tips

Finding Error Details

Common Patterns

See Also