exitcodes.func

#!/usr/bin/env bash
# Copyright (c) 2021-2026 community-scripts ORG
# License: MIT | https://raw.githubusercontent.com/community-scripts/core/main/LICENSE

# ==============================================================================
# API/EXIT CODE EXPLANATIONS
# ==============================================================================
# Part of the telemetry layer. Load api/api.func -- it sources every part --
# rather than this file directly; the split is for maintenance only and no
# function name or behaviour changed with it.
#
# Turns a numeric exit status into a sentence, and sorts it into a category
# for the telemetry field. Almost entirely a lookup table, and the authoritative
# copy of it.
#
# Two things have to move with it. core/error_handler.func carries a fallback
# table for the container case, where this file is not loaded; and the aborted
# branch of post_update_to_api has to agree with the user_aborted codes below,
# or a run is filed as one thing and described as another. The pointer here used
# to name docs/exit_codes.md, which does not exist.

# ==============================================================================

[[ -n "${_API_EXITCODES_LOADED:-}" ]] && return 0
_API_EXITCODES_LOADED=1

# ------------------------------------------------------------------------------
# explain_exit_code()
#
# - Maps numeric exit codes to human-readable error descriptions
# - Canonical source of truth for ALL exit code mappings
# - Used by both api.func (telemetry) and error_handler.func (error display)
# ------------------------------------------------------------------------------
explain_exit_code() {
  local code="$1"
  case "$code" in
  # --- Generic / Shell ---
  # Reached through the aborted branch of post_update_to_api: a clean exit that
  # never reported success is someone backing out of a dialog. Every one of
  # those records read "Unknown error".
  0) echo "Cancelled before completion (no error)" ;;
  1) echo "The command failed; its output says why" ;;
  2) echo "The command failed with status 2 (a usage error for most tools); its output says why" ;;
  3) echo "The command failed with status 3; its output says why" ;;
  10) echo "Docker / privileged mode required (unsupported environment)" ;;

  # --- curl / wget errors ---
  4) echo "curl: Feature not supported or protocol error" ;;
  5) echo "curl: Could not resolve proxy" ;;
  6) echo "curl: DNS resolution failed (could not resolve host)" ;;
  7) echo "curl: Failed to connect (network unreachable / host down)" ;;
  8) echo "curl: Server reply error (FTP/SFTP or apk untrusted key)" ;;
  16) echo "curl: HTTP/2 framing layer error" ;;
  18) echo "curl: Partial file (transfer not completed)" ;;
  22) echo "curl: HTTP error returned (404, 429, 500+)" ;;
  23) echo "curl: Write error (disk full or permissions)" ;;
  24) echo "curl: Write to local file failed" ;;
  25) echo "curl: Upload failed" ;;
  26) echo "curl: Read error on local file (I/O)" ;;
  27) echo "curl: Out of memory (memory allocation failed)" ;;
  28) echo "curl: Operation timeout (network slow or server not responding)" ;;
  30) echo "curl: FTP port command failed" ;;
  32) echo "curl: FTP SIZE command failed" ;;
  33) echo "curl: HTTP range error" ;;
  34) echo "curl: HTTP post error" ;;
  35) echo "curl: SSL/TLS handshake failed (certificate error)" ;;
  36) echo "curl: FTP bad download resume" ;;
  39) echo "curl: LDAP search failed" ;;
  44) echo "curl: Internal error (bad function call order)" ;;
  45) echo "curl: Interface error (failed to bind to specified interface)" ;;
  46) echo "curl: Bad password entered" ;;
  47) echo "curl: Too many redirects" ;;
  48) echo "curl: Unknown command line option specified" ;;
  51) echo "curl: SSL peer certificate or SSH host key verification failed" ;;
  52) echo "curl: Empty reply from server (got nothing)" ;;
  55) echo "curl: Failed sending network data" ;;
  56) echo "curl: Receive error (connection reset by peer)" ;;
  57) echo "curl: Unrecoverable poll/select error (system I/O failure)" ;;
  59) echo "curl: Couldn't use specified SSL cipher" ;;
  61) echo "curl: Bad/unrecognized transfer encoding" ;;
  63) echo "curl: Maximum file size exceeded" ;;
  75) echo "Temporary failure (retry later)" ;;
  78) echo "curl: Remote file not found (404 on FTP/file)" ;;
  79) echo "curl: SSH session error (key exchange/auth failed)" ;;
  92) echo "curl: HTTP/2 stream error (protocol violation)" ;;
  95) echo "curl: HTTP/3 layer error" ;;

  # --- Package manager / APT / DPKG ---
  100) echo "APT: Package manager error (broken packages / dependency problems)" ;;
  101) echo "APT: Configuration error (bad sources.list, malformed config)" ;;
  102) echo "APT: Lock held by another process (dpkg/apt still running)" ;;

  # --- Script Validation & Setup (103-123) ---
  103) echo "Validation: Shell is not Bash" ;;
  104) echo "Validation: Not running as root (or invoked via sudo)" ;;
  105) echo "Validation: Proxmox VE version not supported" ;;
  106) echo "Validation: Unsupported architecture (requires amd64 or arm64)" ;;
  107) echo "Validation: Kernel key parameters unreadable" ;;
  108) echo "Validation: Kernel key limits exceeded" ;;
  109) echo "Proxmox: No available container ID after max attempts" ;;
  110) echo "Proxmox: Failed to apply default.vars" ;;
  111) echo "Proxmox: App defaults file not available" ;;
  112) echo "Proxmox: Invalid install menu option" ;;
  113) echo "LXC: Under-provisioned — user aborted update" ;;
  114) echo "LXC: Storage too low — user aborted update" ;;
  115) echo "Download: install.func download failed or incomplete" ;;
  116) echo "Proxmox: Default bridge vmbr0 not found" ;;
  117) echo "LXC: Container did not reach running state" ;;
  118) echo "LXC: No IP assigned to container after timeout" ;;
  119) echo "Proxmox: No valid storage for rootdir content" ;;
  120) echo "Proxmox: No valid storage for vztmpl content" ;;
  121) echo "LXC: Container network not ready (no IP after retries)" ;;
  122) echo "LXC: No internet connectivity — user declined to continue" ;;
  123) echo "LXC: Local IP detection failed" ;;

  # --- BSD sysexits.h (64-78) ---
  64) echo "Usage error (wrong arguments)" ;;
  65) echo "Data format error (bad input data)" ;;
  66) echo "Input file not found (cannot open input)" ;;
  67) echo "User not found (addressee unknown)" ;;
  68) echo "Host not found (hostname unknown)" ;;
  69) echo "Service unavailable" ;;
  70) echo "Internal software error" ;;
  71) echo "System error (OS-level failure)" ;;
  72) echo "Critical OS file missing" ;;
  73) echo "Cannot create output file" ;;
  74) echo "I/O error" ;;
  76) echo "Remote protocol error" ;;
  77) echo "Permission denied" ;;

  # --- Common shell/system errors ---
  124) echo "Command timed out (timeout command)" ;;
  125) echo "Command failed to start (Docker daemon or execution error)" ;;
  126) echo "Command invoked cannot execute (permission problem?)" ;;
  127) echo "Command not found" ;;
  128) echo "git: Fatal error (repository, network or permission problem)" ;;
  129) echo "Killed by SIGHUP (terminal closed / hangup)" ;;
  130) echo "Aborted by user (SIGINT)" ;;
  131) echo "Killed by SIGQUIT (core dumped)" ;;
  132) echo "Killed by SIGILL (illegal CPU instruction)" ;;
  134) echo "Process aborted (SIGABRT - possibly Node.js heap overflow)" ;;
  137) echo "Killed (SIGKILL / Out of memory?)" ;;
  139) echo "Segmentation fault (core dumped)" ;;
  141) echo "Broken pipe (SIGPIPE - output closed prematurely)" ;;
  143) echo "Terminated (SIGTERM)" ;;
  144) echo "Killed by signal 16 (SIGUSR1 / SIGSTKFLT)" ;;
  146) echo "Killed by signal 18 (SIGTSTP)" ;;

  # --- Systemd / Service errors (150-154) ---
  150) echo "Systemd: Service failed to start" ;;
  151) echo "Systemd: Service unit not found" ;;
  152) echo "Permission denied (EACCES)" ;;
  153) echo "Build/compile failed (make/gcc/cmake)" ;;
  154) echo "Node.js: Native addon build failed (node-gyp)" ;;

  # --- Python / pip / uv (160-162) ---
  160) echo "Python: Virtualenv / uv environment missing or broken" ;;
  161) echo "Python: Dependency resolution failed" ;;
  162) echo "Python: Installation aborted (permissions or EXTERNALLY-MANAGED)" ;;

  # --- PostgreSQL (170-173) ---
  170) echo "PostgreSQL: Connection failed (server not running / wrong socket)" ;;
  171) echo "PostgreSQL: Authentication failed (bad user/password)" ;;
  172) echo "PostgreSQL: Database does not exist" ;;
  173) echo "PostgreSQL: Fatal error in query / syntax" ;;

  # --- MySQL / MariaDB (180-183) ---
  180) echo "MySQL/MariaDB: Connection failed (server not running / wrong socket)" ;;
  181) echo "MySQL/MariaDB: Authentication failed (bad user/password)" ;;
  182) echo "MySQL/MariaDB: Database does not exist" ;;
  183) echo "MySQL/MariaDB: Fatal error in query / syntax" ;;

  # --- MongoDB (190-193) ---
  190) echo "MongoDB: Connection failed (server not running)" ;;
  191) echo "MongoDB: Authentication failed (bad user/password)" ;;
  192) echo "MongoDB: Database not found" ;;
  193) echo "MongoDB: Fatal query error" ;;

  # --- Engine (199) ---
  # Not a failure of the install. It means the engine reported a terminal status
  # without a code to go with it -- the flag file was unreadable, or a caller
  # passed nothing. It used to be reported as 1, which is also what bash returns
  # for any ordinary command failure, so a lost code and a real general error
  # were the same number.

  199) echo "Engine: exit code not reported" ;;

  # --- Proxmox Custom Codes (200-231) ---
  200) echo "Proxmox: Failed to create lock file" ;;
  203) echo "Proxmox: Missing CTID variable" ;;
  204) echo "Proxmox: Missing PCT_OSTYPE variable" ;;
  205) echo "Proxmox: Invalid CTID (<100)" ;;
  206) echo "Proxmox: CTID already in use" ;;
  207) echo "Proxmox: Password contains unescaped special characters" ;;
  208) echo "Proxmox: Invalid container settings (network, DNS, RAM, password, mounts)" ;;
  209) echo "Proxmox: Container creation failed" ;;
  210) echo "Proxmox: Cluster not quorate" ;;
  211) echo "Proxmox: Timeout waiting for template lock" ;;
  212) echo "Proxmox: Storage type 'iscsidirect' does not support containers (VMs only)" ;;
  213) echo "Proxmox: Storage type does not support 'rootdir' content" ;;
  214) echo "Proxmox: Not enough storage space" ;;
  215) echo "Proxmox: Container created but not listed (ghost state)" ;;
  # 197 runs across 70 apps in a fortnight failed here and were filed as a
  # package manager problem: pct returns 255, and 255 is DPKG's fatal error. A
  # container that will not start is not a dependency problem, and calling it one
  # sends everybody looking in the wrong place.
  227) echo "Proxmox: Container created but failed to start" ;;
  216) echo "Proxmox: RootFS entry missing in config" ;;
  217) echo "Proxmox: Storage not accessible" ;;
  218) echo "Proxmox: Template file corrupted or incomplete" ;;
  219) echo "Proxmox: CephFS does not support containers - use RBD" ;;
  220) echo "Proxmox: Unable to resolve template path" ;;
  221) echo "Proxmox: Template file not readable" ;;
  222) echo "Proxmox: Template download failed" ;;
  223) echo "Proxmox: Template not available after download" ;;
  224) echo "Proxmox: PBS storage is for backups only" ;;
  225) echo "Proxmox: No template available for OS/Version" ;;
  226) echo "Proxmox: VM disk import or post-creation setup failed" ;;
  228) echo "Proxmox: Cluster filesystem /etc/pve not available" ;;
  231) echo "Proxmox: LXC stack too old for the template, or its upgrade failed" ;;

  # --- Tools & Addon Scripts (232-238) ---
  232) echo "Tools: Wrong execution environment (run on PVE host, not inside LXC)" ;;
  233) echo "Tools: Application not installed (update prerequisite missing)" ;;
  234) echo "Tools: No LXC containers found or available" ;;
  235) echo "Tools: Backup or restore operation failed" ;;
  236) echo "Tools: Required hardware not detected" ;;
  237) echo "Tools: Dependency package installation failed" ;;
  238) echo "Tools: OS or distribution not supported for this addon" ;;

  # --- Node.js / npm / pnpm / yarn (239-249) ---
  239) echo "npm/Node.js: Unexpected runtime error or dependency failure" ;;
  243) echo "Node.js: Out of memory (JavaScript heap out of memory)" ;;
  245) echo "Node.js: Invalid command-line option" ;;
  246) echo "Node.js: Internal JavaScript Parse Error" ;;
  247) echo "Node.js: Fatal internal error" ;;
  248) echo "Node.js: Invalid C++ addon / N-API failure" ;;
  249) echo "npm/pnpm/yarn: Unknown fatal error" ;;

  # --- Application Install/Update Errors (250-254) ---
  250) echo "App: Download failed or version not determined" ;;
  251) echo "App: File extraction failed (corrupt or incomplete archive)" ;;
  252) echo "App: Required file or resource not found" ;;
  253) echo "App: Data migration required — update aborted" ;;
  254) echo "App: User declined prompt or input timed out" ;;

  # --- DPKG ---
  255) echo "DPKG: Fatal internal error" ;;

  # --- Default ---
  *) echo "Unknown error" ;;
  esac
}

# ------------------------------------------------------------------------------
# categorize_error()
#
# - Maps exit codes to error categories for dashboard grouping
# - Can be overridden via ERROR_CATEGORY_OVERRIDE (log-based subclassification)
# ------------------------------------------------------------------------------

# ------------------------------------------------------------------------------
# categorize_error()
#
# - Maps exit codes to error categories for dashboard grouping
# - Can be overridden via ERROR_CATEGORY_OVERRIDE (log-based subclassification)
# ------------------------------------------------------------------------------
categorize_error() {
  if [[ -n "${ERROR_CATEGORY_OVERRIDE:-}" ]]; then
    echo "$ERROR_CATEGORY_OVERRIDE"
    return
  fi

  local code="$1"
  case "$code" in
  6 | 7 | 22 | 35) echo "network" ;;
  10) echo "config" ;;
  28 | 124 | 211) echo "timeout" ;;
  214 | 217 | 219 | 224) echo "storage" ;;
  100 | 101 | 102 | 127 | 160 | 161 | 162 | 255) echo "dependency" ;;
  126 | 152) echo "permission" ;;
  128 | 203 | 204 | 205 | 206 | 207 | 208) echo "config" ;;
  200 | 209 | 210 | 212 | 213 | 215 | 216 | 218 | 220 | 221 | 222 | 223 | 225 | 227 | 228 | 231) echo "proxmox" ;;
  150 | 151 | 153 | 154) echo "service" ;;
  170 | 171 | 172 | 173 | 180 | 181 | 182 | 183 | 190 | 191 | 192 | 193) echo "database" ;;
  243 | 245 | 246 | 247 | 248 | 249) echo "runtime" ;;
  # Kept in step with the aborted branch of post_update_to_api: a code that
  # makes the run "aborted" must not describe itself as something else here.

  113 | 114 | 122 | 129 | 130 | 143 | 253 | 254) echo "user_aborted" ;;
  134 | 137) echo "resource" ;;
  139 | 141) echo "signal" ;;
  1 | 2) echo "shell" ;;
  *) echo "unknown" ;;
  esac
}

# ==============================================================================
# SECTION 2: JSON & LOG HELPERS
# ==============================================================================

# ------------------------------------------------------------------------------
# json_escape()
#
# - Escapes a string for safe JSON embedding
# - Strips ANSI escape sequences and non-printable control characters
# - Uses jq when available (guaranteed correct), falls back to awk
# ------------------------------------------------------------------------------