# Troubleshooting Find common build and installation errors, understand the cause, and choose the next step. Source: https://debark.dev/docs/operate/troubleshooting --- Start with the command’s error message and exit code. The table below links to common problems. | Problem | Where to look | | ----------------------------------------- | ----------------------------------------------------------------- | | Build produced an incomplete bundle | [Exit 3](#exit-3-from-a-build) | | apt cannot resolve the requested packages | [Exit 5](#exit-5-from-a-build) | | Policy rejected the build | [Exit 6](#exit-6-from-a-build) | | Missing tools, permissions, or disk space | [Exit 2](#exit-2-from-any-command) | | Signature or file check failed | [Verification failure](#verify-fails-with-exit-4) | | Wrong target architecture | [Exit 7](#install-stops-with-exit-7) | | Missing dependencies after installation | [Unmet dependencies](#unmet-dependencies-after-installing) | | Package needs the Snap Store | [Snap packages](#snap-packages) | | Package setup needs the network | [Maintainer scripts](#a-maintainer-script-that-wants-the-network) | | Kernel module will not build | [DKMS and headers](#a-dkms-package-with-no-matching-headers) | ## Exit 3 from a build The bundle was written, but some requested inputs are missing or unresolved. Do not treat the folder’s existence as a successful build. Read the affected inputs in the build report or `debark inspect ./bundle`. - For a failed URL, check the address and retry. You can also download the file separately and pass its local path. - For a vendor package with missing dependencies, check that it was built for the target release and architecture. - If the missing dependency comes from another vendor package, include that package too. Rebuild and confirm exit code 0 before transferring it. See [Exit codes](/docs/reference/exit-codes#exit-3-incomplete). ## Exit 5 from a build apt could not satisfy the package request. Its error message usually names the conflicting or unavailable package. Check whether the requested version still exists in the target’s repositories, whether the required repository component is enabled, and whether a package hold or pin prevents the change. Repository settings come from the target snapshot. If you change them on the target, capture a new snapshot before rebuilding. ## Exit 6 from a build A policy rule or the approved archive key list rejected the build. Read the named rule, then check the affected package, source, or fingerprint. Choose an allowed package or correct its source information. Change the policy only if the existing rule does not match your requirements. For a rejected URL, an independently obtained checksum supplied with `--digest` may satisfy a publisher-verification rule. [Policy and package checks](/docs/guides/policy-and-doctor) explains the available rules. ## Exit 2 from any command Read the message for the missing resource. Common causes include: - No suitable apt installation or working Docker/Podman runtime on the builder. - No Linux helper binary when building through a container from Windows or macOS. - Insufficient space in the output folder or download cache. - Missing permission to read a key, write an output file, or install packages. For container setup, see [Build backends](/docs/concepts/backends). For disk space, move the cache with the `store_dir` configuration setting or use [cache cleanup](/docs/concepts/store-and-incremental). ## verify fails with exit 4 Get a detailed report: ```bash debark verify ./bundle --key operator.pub --json ``` | Problem kind | Next step | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `signature-invalid` | Check that you supplied the builder’s correct public key. If the key is correct, obtain a fresh signed bundle. | | `file-digest-mismatch` | A file changed or was damaged. Copy the original bundle again and verify the new copy. | | `file-unexpected` | The folder contains a file absent from the manifest. Start from a clean copy of the original bundle. | | `file-not-regular` | A listed file has become a directory, link, or other file type. Check how the bundle was copied or extracted. | | `same-media-key-refused` | The key path is inside the bundle. Obtain the key independently from the builder. Moving an untrusted key elsewhere does not establish trust. | Do not use `--allow-unsigned` to work around a signature failure. It removes the requirement for a valid signature and does not repair damaged files. ## install stops with exit 7 Compare the target architecture with the bundle: ```bash dpkg --print-architecture debark inspect ./bundle ``` Rebuild using a snapshot captured on this machine. If you must use a stock base, set `--arch` to the architecture reported by `dpkg`. A release mismatch produces a warning rather than exit 7. Check it too: matching architecture alone does not make a bundle suitable for another release. ## Unmet dependencies after installing On the target, run: ```bash sudo apt-get check ``` A stale snapshot or an unsuitable stock base can leave the build based on the wrong installed package set. Capture a fresh snapshot of the affected machine, rebuild on the online builder, and preview the new bundle with `install --status`. If a package’s configuration script failed, inspect that error as well. Adding dependency files will not fix a script that needs an unavailable service or download. ## Snap packages Some Ubuntu package names resolve to small `.deb` packages that install the actual application through Snap. Which packages behave this way depends on the release. Debark bundles `.deb` files; it does not download or install their Snap payloads. `doctor` can flag known cases as `snap-shim`. Use a supported native `.deb` distribution of the application, if one is available, or prepare the Snap and its required dependencies separately using Snap’s offline installation instructions. Files transferred separately are not covered by the bundle’s manifest or verification. ## A maintainer script that wants the network A package can include all its apt dependencies and still download files or register with a server during setup. ```bash debark doctor ./bundle ``` A `network-postinst` finding points to a possible network action in a package script. Review the package’s own offline setup instructions. You may need to provide extra assets or configuration before installing, or choose another package. The scan is a heuristic: an empty report does not guarantee every installation script works offline. ## A DKMS package with no matching headers DKMS packages compile kernel modules on the target. Check the running kernel there: ```bash uname -r ``` Include the matching kernel headers in the bundle if the target does not already have them. Use the exact kernel version reported by the target when choosing the headers; the newest generic headers may be for a different kernel. After installation, use `dkms status` to check whether the module was built and installed. ## Interactive mode will not run in CI `--interactive` requires a terminal and cannot be combined with `--json` or `--json-events`. Run the guided build on a workstation to work out the options, then use its equivalent noninteractive command in your script. See [Automate builds](/docs/guides/automation). ## The bundle came out unsigned Use an explicit signing key when a signature is required: ```bash debark build --snapshot target.snapshot.tar.zst \ --out ./bundle --sign operator.key jq debark verify ./bundle --key operator.pub ``` Check `debark config show` if you expected a default `sign_key`. A missing configuration on another machine can change the signing behavior. ## A path with spaces If apt reports an invalid local repository path, copy the bundle to a simple path such as `/srv/bundle`, verify that copy, and retry. Quote paths containing spaces in shell commands. ## Windows line endings A shell script saved with CRLF line endings can fail on Linux with `bad interpreter` or `^M` in the message. Save the script with LF line endings in your editor, then copy it again. For scripts kept in Git, a `.gitattributes` rule such as `*.sh text eol=lf` avoids this on future checkouts. ## Report a bug Include the Debark version, operating system, command, exit code, and error message. Add JSON output when available: ```bash debark version debark verify ./bundle --key operator.pub --json > report.json ``` For build failures, `--json-events events.ndjson` can show where the command stopped. Review reports before sharing them: paths, repository URLs, labels, and package lists may contain private information. Open a [GitHub issue](https://github.com/inferops/debark/issues) for a bug. For security issues, follow [Reporting a vulnerability](/docs/trust/trust-model#reporting-a-vulnerability).