# Exit codes Look up command exit codes and decide how to handle a failed or incomplete run. Source: https://debark.dev/docs/reference/exit-codes --- Use the exit code to detect success or failure in a script. Read the error message or JSON report for the specific cause. In Bash, `echo $?` prints the preceding command’s code. In PowerShell, use `$LASTEXITCODE`. ## Code table | Code | Class | Meaning | | ---- | ----------------- | ----------------------------------------------------------------------------------------------------------------- | | 0 | `success` | The command completed successfully. Warnings may still be present. | | 1 | `usage` | Invalid arguments or configuration, or an otherwise unclassified error. | | 2 | `environment` | A required tool, permission, file resource, or disk space is unavailable. Internal errors can also use this code. | | 3 | `incomplete` | A bundle was written, but some inputs are missing or unresolved. | | 4 | `verification` | A signature, file, or metadata check failed. | | 5 | `resolution` | apt could not satisfy the request, or installation failed for a package-related reason. | | 6 | `policy` | A build violated a policy rule or approved archive key requirement. | | 7 | `target-mismatch` | The bundle and target architectures do not match. | ## Exit 1: usage Check the command syntax and configuration. Common causes include unknown flags, an invalid profile, malformed YAML, or incompatible options. For a build, do not combine: - `--snapshot` with `--base`. - `--out` with `--tar`. - `--sign` with `--no-sign`. - `--recommends` with `--no-recommends`. - `--arch` with `--snapshot`. `--interactive` requires a terminal and cannot be used with JSON output or event streaming. ## Exit 2: environment Check the resource named in the message. You may need to start Docker or Podman, provide the Linux container helper, free disk space, or correct file permissions. An error described as an internal error should be reported as a bug. See [Troubleshooting](/docs/operate/troubleshooting#report-a-bug). ## Exit 3: incomplete A bundle folder or archive exists, but it does not contain everything requested. Examples include a failed vendor URL or a vendor package whose dependencies could not be satisfied. Read the affected inputs in the report, correct them, and rebuild. Do not publish or install the result as a complete bundle just because files were written. A signature or successful file check does not resolve missing package inputs. ## Exit 4: verification The bundle failed a signature, file, or metadata check. `install` stops before applying packages when this happens. Check the expected public key and the reported problem kind. If a file changed or was damaged, obtain a fresh copy and verify again. See [Verify a bundle](/docs/trust/verifying). ## Exit 5: resolution For builds, read apt’s explanation of the unavailable package, version conflict, hold, or missing repository component. For installs, inspect the package-manager error and resulting package state. An installation can fail after changes have started, so this code does not imply that nothing changed. A previous output folder may still exist after a failed build. Check the current command’s result before using it. ## Exit 6: policy Read the named rule or archive key requirement. Change the package request or correct the source information. Update the policy only if its rule does not match your intended requirements. `doctor` findings do not return code 6. A completed doctor scan returns 0 even with warnings; read its report if your script needs to act on those findings. Errors reading or scanning its input can still return nonzero. ## Exit 7: target mismatch Rebuild for the target’s architecture, preferably from its own snapshot. A release mismatch during installation produces a warning rather than this code. Check release warnings before proceeding. ## Handle failures in a script This Bash example stops on every unsuccessful build, while giving an incomplete result a clearer message: ```bash #!/usr/bin/env bash set -euo pipefail if debark build --snapshot target.snapshot.tar.zst \ --out ./bundle --sign operator.key jq; then debark verify ./bundle --key operator.pub else status=$? if [ "$status" -eq 3 ]; then echo "Bundle incomplete: fix the reported inputs and rebuild." >&2 else echo "Build failed with exit code $status." >&2 fi exit "$status" fi ``` The example assumes the snapshot and signing keys already exist. See [Automate builds](/docs/guides/automation) for JSON reports and saved events.