mirror of https://github.com/community-scripts/ProxmoxVE.git synced 2026-02-17 18:53:27 +01:00

Go to file

CanbiZ (MickLesk) c9ecb1ccca core: smart recovery for failed installs | extend exit_codes (#11221 )

* feat(build.func): smart error recovery menu for failed installations

Replace simple Y/n removal prompt with interactive recovery menu:

- Option 1: Remove container and exit (default, auto after 60s timeout)
- Option 2: Keep container for debugging
- Option 3: Retry installation with verbose mode enabled
- Option 4: Retry with 1.5x RAM and +1 CPU core (OOM errors only)

Improvements:
- Detect OOM errors (exit codes 137, 243) and offer resource increase
- Show human-readable error explanation using explain_exit_code()
- Recursive rebuild preserves ALL settings from advanced/app.vars/default.vars
- Settings preserved: Network (IP, Gateway, VLAN, MTU, Bridge), Features
  (Nesting, FUSE, TUN, GPU), Storage, SSH keys, Tags, Hostname, etc.
- Show rebuild summary before retry (old→new CTID, resources, network)
- New container ID generated automatically for rebuilds

This helps users recover from transient failures without re-running
the entire script manually.

* fix(api.func): fix duplicate exit codes and add missing error codes

Exit code fixes:
- Remove duplicate definitions for codes 243, 254 (Node.js vs DB)
- Reassign MySQL/MariaDB to 240-242, 244 (was 241-244)
- Reassign MongoDB to 250-253 (was 251-254)

New exit codes added (based on GitHub issues analysis):
- 6: curl couldn't resolve host (DNS failure)
- 7: curl failed to connect (network unreachable)
- 22: curl HTTP error (404, 429 rate limit, 500)
- 28: curl timeout (very common in download failures)
- 35: curl SSL error
- 102: APT lock held by another process
- 124: Command timeout
- 141: SIGPIPE (broken pipe)

Also update OOM detection to include exit code 134 (SIGABRT)
which is commonly seen in Node.js heap overflow issues.

Fixes based on analysis of ~500 GitHub issues.

* fix(exit-codes): sync error_handler.func and api.func with conflict-free code ranges

- Add curl error codes (6, 7, 22, 28, 35)
- Add APT lock code (102), timeout (124), signals (134, 141)
- Move Python codes: 210-212 → 160-162 (avoid Proxmox conflict)
- Move PostgreSQL codes: 231-234 → 170-173
- Move MySQL/MariaDB codes: 241-244 → 180-183
- Move MongoDB codes: 251-254 → 190-193
- Keep Node.js at 243-249, Proxmox at 200-231
- Both files now synchronized with identical mappings

* feat(exit-codes): add systemd and build error codes (150-154)

- 150: Systemd service failed to start
- 151: Systemd service unit not found
- 152: Permission denied (EACCES)
- 153: Build/compile failed (make/gcc/cmake)
- 154: Node.js native addon build failed (node-gyp)

Based on issue analysis: 57 service failures, 25 build failures, 22 node-gyp issues

* fix(build): restore smart recovery and add OOM/DNS retry paths

* feat(build): APT in-place repair, exit 1 subclassification, new exit codes

- Add APT/DPKG in-place recovery: detects exit 100/101/102/255 and exit 1
  with APT log patterns, offers to repair dpkg state and re-run install
  script without destroying the container
- Add exit 1 subclassification: analyzes combined log to identify root
  cause (APT, OOM, network, command-not-found) and routes to appropriate
  recovery option
- Add exit 10 hint: shows privileged mode / nesting suggestion
- Add exit 127 hint: extracts missing command name from logs
- Refactor recovery menu: use named option variables (APT_OPTION,
  OOM_OPTION, DNS_OPTION) instead of hardcoded option numbers, supports
  up to 6 dynamic options cleanly
- Map missing exit codes in api.func: curl 27/36/45/47/55, signals
  129 (SIGHUP) / 131 (SIGQUIT), npm 239

* feat(api+build): map 25 more exit codes, add SIGHUP trap, network/perm hints

api.func:
- Map 25+ new exit codes that were showing as 'Unknown' in telemetry:
  curl: 3, 16, 18, 24, 26, 32-34, 39, 44, 46, 48, 51, 52, 57, 59, 61,
  63, 79, 92, 95; signals: 125, 132, 144, 146
- Update code 8 description (FTP + apk untrusted key)
- Update header comment with full supported ranges

build.func:
- Add SIGHUP trap: reports 'failed/129' to API when terminal is closed,
  should significantly reduce the 2841 stuck 'installing' records
- Add exit 52 (empty reply) and 57 (poll error) to network issue
  detection for DNS override recovery option
- Add exit 125/126 hint: suggests privileged mode for permission errors

* fix: sync error_handler fallback, Alpine APK repair, retry limit

error_handler.func:
- Sync fallback explain_exit_code() with api.func: add 25+ codes that
  were missing (curl 16/18/24/26/27/32-34/36/39/44-48/51/52/55/57/59/
  61/63/79/92/95, signals 125/129/131/132/144/146, npm 239, code 3/8)
- Ensures consistent error descriptions even when api.func isn't loaded

build.func:
- Alpine APK repair: detect var_os=alpine and run 'apk fix && apk
  cache clean && apk update' instead of apt-get/dpkg commands
- Show 'Repair APK state' instead of 'APT/DPKG' in menu for Alpine
- Retry safety counter: OOM x2 retry limited to max 2 attempts
  (prevents infinite RAM doubling via RECOVERY_ATTEMPT env var)
- Show attempt count in rebuild summary

* fix(build): preserve exit code in ERR trap to prevent false exit_code=0

The ERR trap called ensure_log_on_host before post_update_to_api,
which reset \True to 0 (success). This caused ~15-20 records/day to be
reported as 'failed' with exit_code=0 instead of the actual error code.

Root cause chain:
1. Command fails with exit code N → ERR trap fires (\True = N)
2. ensure_log_on_host succeeds → \True becomes 0
3. post_update_to_api 'failed' '\True' → sends 'failed/0' (wrong!)
4. POST_UPDATE_DONE=true → EXIT trap skips the correct code

Fix: capture \True into _ERR_CODE before ensure_log_on_host runs.

* Implement telemetry settings and repo source detection

Add telemetry configuration and repository source detection function.

2026-02-17 12:14:46 +01:00

.github

github: add "website" label if "json" changed (#11975 )

2026-02-16 10:51:49 +01:00

.vscode

re-add shellcheck exclusions (#10586 )

2026-01-06 13:27:23 +01:00

Update .app files (#12022 )

2026-02-17 10:45:09 +01:00

docs

fix(setup): correctly auto-detect username when using --full (#11650 )

2026-02-07 19:44:47 +01:00

frontend

Update date in json (#12021 )

2026-02-17 09:41:19 +00:00

install

Databasus (#12018 )

2026-02-17 10:40:58 +01:00

misc

core: smart recovery for failed installs | extend exit_codes (#11221 )

2026-02-17 12:14:46 +01:00

tools

Feature/lxc update patchmon aware (#11905 )

2026-02-14 16:42:29 +01:00

turnkey

core: validate container ID before pct create to prevent failures (#10729 )

2026-01-12 14:04:28 +01:00

core/vm's: ensure script state is sent on script exit (#11991 )

2026-02-16 17:14:00 +01:00

.editorconfig

Update repo tree to fix .editorconfig beign ignored. (#3302 )

2025-03-21 15:53:30 +01:00

.gitattributes

linguist - enable visible jsons in pr's

2025-07-17 15:14:05 +02:00

.gitignore

ignore vscode/settings.json

2025-04-15 15:58:05 +02:00

CHANGELOG.md

Update CHANGELOG.md (#12023 )

2026-02-17 09:41:25 +00:00

LICENSE

chore: bump copyright to 2026 - happy new year (#10585 )

2026-01-06 13:28:12 +01:00

README.md

Update project statistics in README

2025-12-15 10:06:07 +01:00

SECURITY.md

gh: update supported PVE Version (#9422 )

2025-11-25 08:52:46 +01:00

README.md

Proxmox VE Helper-Scripts

A Community Legacy in Memory of @tteck

Simplify your Proxmox VE setup with community-driven automation scripts
Originally created by tteck, now maintained and expanded by the community

_{🙌 Shoutout to}

_{View on GitHub • Consistent, beautiful icons for 5000+ self-hosted apps}

🎯 Key Features

⚡ Quick Setup

One-command installations for popular services and containers

⚙️ Flexible Config

Simple mode for beginners, advanced options for power users

🔄 Auto Updates

Keep your installations current with built-in update mechanisms

🛠️ Easy Management

Post-install scripts for configuration and troubleshooting

👥 Community Driven

Actively maintained with contributions from users worldwide

📖 Well Documented

Comprehensive guides and community support

🔒 Secure

Regular security updates and best practices

⚡ Performance

Optimized configurations for best performance

📋 Requirements

🖥️ Proxmox VE

Version: 8.4.x | 9.0.x | 9.1.x

🐧 Operating System

Debian-based with Proxmox Tools

🌐 Network

Internet connection required

📥 Getting Started

Choose your preferred installation method:

Method 1: One-Click Web Installer

The fastest way to get started:

Visit helper-scripts.com 🌐
Search for your desired script (e.g., "Home Assistant", "Docker")
Copy the bash command displayed on the script page
Open your Proxmox Shell and paste the command
Press Enter and follow the interactive prompts

Method 2: PVEScripts-Local

Install a convenient script manager directly in your Proxmox UI:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pve-scripts-local.sh)"

This adds a menu to your Proxmox interface for easy script access without visiting the website.

📖 Learn more: ProxmoxVE-Local Repository

💬 Join the Community

💬 Discord

Real-time chat, support, and discussions

💭 Discussions

Feature requests, Q&A, and ideas

🐛 Issues

Bug reports and issue tracking

🛠️ Contribute

💻 Code

Add new scripts or improve existing ones

📝 Documentation

Write guides, improve READMEs, translate content

🧪 Testing

Test scripts and report compatibility issues

💡 Ideas

Suggest features or workflow improvements

👉 Check our Contributing Guidelines to get started

❤️ Support the Project

This project is maintained by volunteers in memory of tteck. Your support helps us maintain infrastructure, improve documentation, and give back to important causes.

🎗️ 30% of all donations go directly to cancer research and hospice care

_{Every contribution helps keep this project alive and supports meaningful causes}

📈 Project Statistics

📜 License

This project is licensed under the MIT License - feel free to use, modify, and distribute.

_{Made with ❤️ by the Proxmox community in memory of tteck}
_{Proxmox® is a registered trademark of Proxmox Server Solutions GmbH}