Troubleshooting

Start with the narrowest layer that can explain the failure. Keep the full command, package origin, selected reference, cpak build, and host capability report with any bug report.

Run the host check

cpak doctor
cpak doctor --json

A required namespace or OverlayFS failure blocks application startup. Landlock and cgroup warnings describe protection or limits that the current host cannot apply.

Read application logs

cpak logs github.com/example/app
cpak logs --lines 300 github.com/example/app
cpak logs --follow github.com/example/app

Use --instance when the package has more than one running instance. Nested dependency failures may have their own origin and log stream.

Open a package shell

cpak shell github.com/example/app

Check that declared binaries, desktop files, libraries, and mounted paths exist. Compare the package environment with the cpak.json permission set before adding more access.

Reproduce a local package

Inside a package repository:

cpak validate cpak.json
cpak lock cpak.json
cpak test cpak.json --binary /usr/bin/example -- --version
cpak dev cpak.json --binary /usr/bin/example

These commands use a temporary store and isolate package debugging from installed applications.

Check permissions

Symptoms such as a missing window, silent audio, inaccessible files, failed browser sandbox, or blocked external link usually map to one concrete permission. Review display sockets, audio, DRI, filesystem paths, userNamespaces, and broker fields.

Do not enable the session bus, system bus, all devices, or host root as a generic fix. Confirm the resource the application attempted to access.

Repair store state

cpak audit
cpak audit --repair
cpak gc --json

Repair mode cleans invalid container records, removes unreferenced store data, and restricts cpak metadata directories to their owner. It leaves image contents, prepared checkouts, private application homes, and writable environment data unchanged.

If audit reports that a layer or prepared checkout contradicts its recorded state, update or reinstall that package. Repair mode cannot turn the current files into a fresh registry pull. Garbage collection removes unreferenced content after the record graph is consistent.

Desktop entry does not appear

Confirm that the manifest path is absolute, ends in .desktop, and exists in the final image. Its Exec target must be a declared or available binary. Reinstall or update the package after changing only manifest metadata so cpak refreshes the exported entry.

An application refuses to start after verified launch is on

Run cpak system explain <origin>: it puts what the ledger holds beside what the launch derives, which is the difference between an application nobody enrolled and one whose store no longer holds what it recorded.

An application that was never enrolled is refused only at refuse. Update it, or run cpak audit --backfill-bindings for an installation made before verified launch existed.

A store that contradicts itself is refused at every level, including off, and that is deliberate: it is not an unknown, it is a disagreement inside the store. cpak update <origin> records the application again from what the registry serves.

Changing permissions with cpak override, or enabling an addon, changes what a launch derives, so cpak records the application again as part of the same command. A narrower permission set is recorded without asking. A wider one asks for an administrator password, once, and declining it leaves the application updated but unenrolled.

A login session does not appear in the display manager

Run cpak system status first: on a host with a read-only /usr/local the integration installs under another prefix, and the session directory moves with it. cpak system setup prints what it could not configure, so read its output. SDDM and LightDM are configured through their own files and work under any init. GDM and greetd read the directory from their service environment, which cpak sets automatically under systemd and OpenRC only; under runit, s6, dinit, and sysvinit the setup reports the directory to add and to which service. A greeter that sets XDG_DATA_DIRS itself has to list the directory too, because its own value wins.

A cpak application is not used as the default

Check both desktop resolvers:

xdg-mime query default x-scheme-handler/https
gio mime x-scheme-handler/https

The result may be the hidden original desktop ID or the visible cpak-prefixed ID. Run cpak update for the package when the configured original ID no longer exists. The update refreshes both entries without changing application data.

A link opens inside the wrong package

The package needs openURI. cpak provides xdg-open, gio open, and a private GIO handler for common external links. Check the application log for an attempted nested launch. That message means an old runtime resolved a host desktop entry inside the package instead of using the URI broker. Update cpak, stop the package instance, and start it again so its runtime policy is rebuilt.

An update is refused

Inspect the structured update result:

cpak update --json github.com/example/app

permission-denied means the new package requested additional access in a non-interactive flow or the user declined it. pinned means the installed commit is intentionally immutable.

Report a reproducible problem

Include:

• the output of cpak doctor --json
• the exact command and exit status
• the package origin and selected branch, release, or commit
• the relevant cpak logs excerpt
• the smallest sequence that reproduces the failure

Hide credentials, home directory names, and unrelated environment values. Use code fences for long logs.