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
apt cannot resolve the requested packages	Exit 5
Policy rejected the build	Exit 6
Missing tools, permissions, or disk space	Exit 2
Signature or file check failed	Verification failure
Wrong target architecture	Exit 7
Missing dependencies after installation	Unmet dependencies
Package needs the Snap Store	Snap packages
Package setup needs the network	Maintainer scripts
Kernel module will not build	DKMS and 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.

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 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. For disk space, move the cache with the store_dir configuration setting or use cache cleanup.

verify fails with exit 4

Get a detailed report:

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:

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:

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.

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:

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.

The bundle came out unsigned

Use an explicit signing key when a signature is required:

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:

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 for a bug. For security issues, follow Reporting a vulnerability.