Error handling

Error handling lives in core/error_handler.func. A script enables it with one call and from then on must not install its own ERR or EXIT traps.

catch_errorsCopy Anchor Link

catch_errors

No arguments. It runs set -Ee -o pipefail and installs five traps:

set -u is added only when STRICT_UNSET=1.

Who calls it:

• ui/build-ui.func right after loading core/core.func and this file, so the engine is covered while it loads.

• Every ct script, after variables and color (ct/vaultwarden.sh):

  Copy Text

  header_info "$APP"
  variables
  color
  catch_errors

  On a Proxmox VE host this second call matters: pve/backend.func sets its own EXIT, ERR, INT and TERM traps when it loads, and the script's catch_errors puts the handlers described here back in place.

• lxc/install.func during the container bootstrap, and every install script again after verb_ip6 (install/vaultwarden-install.sh):

  Copy Text

  source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
  color
  verb_ip6
  catch_errors
  setting_up_container
  network_check
  update_os

• Add-on scripts, after sourcing the files themselves.

On Incus hosts incus/core.func redefines catch_errors and error_handler as its own incus_catch_errors and incus_error_handler, and incus/build.func installs its own signal traps. The rest of this page describes the handlers in core/error_handler.func, which are the ones used on Proxmox VE hosts and inside containers on both platforms.

What "failure" meansCopy Anchor Link

With set -e and the ERR trap, any command that returns non-zero ends the run, unless it is part of a condition (if, while, &&, ||) or you add || true. Commands run through $STD behave the same way: silent returns the command's status and the trap fires on that line.

What error_handler doesCopy Anchor Link

In order:

1. Works out the exit code, the command and the line. If the failing command ran through silent, the real command, its line and its captured output replace what the trap saw (which would only be the silent wrapper or a helper's return).
2. Treats the failure as exit 130 when the captured output shows that the command received a Ctrl-C (received signal 2 or KeyboardInterrupt).
3. Inside a $( ) or ( ) subshell it only exits with the code; the calling shell fails on the same error and reports it once.
4. Stops the spinner and restores the cursor.
5. Reports the failure once (see Who reports).
6. Prints the error line.
7. Prints what the failing command printed.
8. Prints hints for known causes.
9. On the host: prints Full log: <path> and offers to remove a half-built container.
10. Exits with the original exit code.

The error lineCopy Anchor Link

✖️  in line 24: exit code 100 (APT: Package manager error (broken packages / dependency problems)): while executing command apt install -y build-essential

The explanation normally comes from explain_exit_code, the table on the Exit codes page. The handler adjusts it to the command that actually ran, because many tools reuse the same numbers:

So cargo build failing with 101 is reported as cargo exited with status 101, not as the APT configuration error that 101 means for apt.

Output of the failing commandCopy Anchor Link

One of three blocks follows the error line, written to stderr:

HintsCopy Anchor Link

The log-based hints look at the last 60 lines of the log and only the first matching row is shown.

Who reports: host and containerCopy Anchor Link

One run sends one terminal telemetry event, and the host sends it.

The handler decides which side it is on with TELEMETRY_CONTEXT (lxc/install.func exports container), and otherwise by looking for pveversion, pct or incus.

The container is not silent on telemetry altogether: lxc/install.func sends progress pings (post_progress_to_api) while the install runs. Only the final status comes from the host. See Telemetry.

The .errinfo captureCopy Anchor Link

Written by silent and by the error handler; the format is defined at the top of api/errorlog.func:

EXIT_CODE=100
LINE=24
COMMAND=apt install -y build-essential
FUNCTION=setup_deb_based
STEP=Installing Dependencies
MESSAGE=
PHASE=container
--- OUTPUT ---
E: Unable to locate package build-essential

STEP is the text of the msg_info that was open, or after <text> of the last msg_ok. MESSAGE is the first msg_error of that step. PHASE is host or container.

build_error_string turns this into the trace telemetry receives:

exit_code=100 | APT: Package manager error (broken packages / dependency problems) | step: Installing Dependencies | in setup_deb_based | at line 24: apt install -y build-essential
---
E: Unable to locate package build-essential

Before it is sent, the output is reduced to the failing step, package-manager and download progress lines are removed, IPv4 addresses are shortened to <first octet>.x.x.x, and the result is limited to 60 lines and 10240 bytes.

Failures on the hostCopy Anchor Link

When a host-side step fails after the container exists, the handler asks:

Remove broken container 105? (Y/n) [auto-remove in 60s]:

The question is only asked for a container this run created (_CS_CREATED_CTID). An add-on that sets CTID to an existing container never gets it.

The recovery menu after a failed installCopy Anchor Link

A failure of the install script inside the container is handled by build_container in pve/backend.func, not by the ERR trap. After lxc-attach returns, the host reads /root/.install-<SESSION_ID>.failed from the container. If it exists (or lxc-attach itself returned non-zero), the host:

1. prints Installation failed in container <CTID> (exit code: N);
2. builds a combined log, /tmp/<app>-<CTID>-<SESSION_ID>.log, from the host build log ("PHASE 1") and the install log pulled out of the container ("PHASE 2"), and pulls the .errinfo capture;
3. reports the failure to telemetry;
4. prints Installation log: <path> and Error: <explanation>;
5. shows the menu.

What would you like to do?

  1) Remove container and exit
  2) Keep container for debugging
  3) Retry with verbose mode (full rebuild)
  4) Repair APT/DPKG state and re-run install (in-place)

Select option [1-4] (default: 1, auto-remove in 60s):

Options 1 to 3 are always there. The others appear when the failure looks like a case they can fix, and are numbered from 4 in this order:

How the prompt resolves:

If the in-place repair does not help, the container is kept and the script exits with the new code. A rebuild that succeeds continues as a normal install.

Extra lines above the menu explain some codes: exit 10 (the container probably needs privileged mode or nesting), exit 125/126 (permission problem), a full disk (with the current disk size), and a missing command (its name).

Two dev mode flags skip the menu: keep leaves the container untouched, breakpoint opens a shell in it.

On Incus, incus/backend.func has its own version of this step.

on_exitCopy Anchor Link

Runs on every exit and keeps the exit code.

SignalsCopy Anchor Link

Closing the consoleCopy Anchor Link

Closing the browser console or losing the SSH session sends SIGHUP. The run is not aborted:

• on_hangup points stdin at /dev/null and stdout/stderr at the active log, exports _CS_HANGUP=1, and writes The terminal closed; continuing, output follows here. to the log.
• Programs started through $STD ignore SIGHUP and finish.
• On the host, lxc-attach dies with the terminal but the install inside the container keeps running. The host then waits for /root/.install-<SESSION_ID>.done or .failed in the container, checking every 15 seconds for up to six hours.
• If the install then fails, nobody can answer the recovery menu, so the container is kept.

To watch an install whose console you closed:

pct exec <CTID> -- tail -f /root/.install-<SESSION_ID>.log

Ctrl-C does abort.

What is logged whereCopy Anchor Link

SESSION_ID is the first eight characters of the run's random UUID. With dev_mode=logs the host build log is written to /var/log/community-scripts/ instead of /tmp.

Log lines written by the message functions look like this:

[2026-01-15 10:32:07] [INFO] Installing Dependencies
[2026-01-15 10:32:41] [OK] Installed Dependencies

Rules for script authorsCopy Anchor Link

• Call catch_errors once, where the templates do. Do not add trap … ERR or trap … EXIT of your own.
• Do not call the telemetry API from an install script.
• Let commands fail with their real exit status. Use an explicit exit <code> only with a code from the exit-code table that says what happened.
• Print a msg_error before a deliberate exit; it becomes the failure's message.
• Use || true for commands that may fail, not set +e.