Reporting a broken snap

Snaps, and the snapd environment, are designed to be stable and secure, especially when they’re installed from a stable channel. But as with all complex software, issues do sometimes occur.

This is a guide to reporting problems if they do occur. It covers how to collect the most useful information, including logs, and how to best share that data on the forum, hopefully leading to a solution.

Reporting problems is a great way of contributing back to the community. Thanks in advance for your help!

Snap developers wanting to solve common runtime errors should take a look at Debugging snaps.

Capturing output

Capturing the output from a broken snap, as well as any associated tools and settings, is an essential part of reporting a problem. There are many ways to do this, with the easiest being to simply copy the output.

If you’d prefer to save error output to a file, use the redirection symbol (>) or the append symbol (>>) followed by a file name:

$ snap list > output.txt
$ snap list -all >> output.txt

Output can also be paused and paged through by piping the output into the more or less commands:

$ snap list -all | more

As some output information can be lengthy, it can help to use a Pastebin service, such as https://pastebin.ubuntu.com. Pastebinit is a great utility that can take the output of a command and automatically paste it to a site like this.

When pasting output into a forum post directly, it also helps to place the output between three back-tick characters ( ``` output ```).

Gathering basic details

snapd version

snapd is the background service that manages and maintains your snaps. It also provides the snap command. The first thing you should include when reporting an issue is which version of snap is being used, and this can be output by typing snap version:

$ snap version
snap    2.54.2
snapd   2.54.2
series  16
ubuntu  20.04
kernel  5.11.0-1028-gcp

snapd package

It’s also useful to have details on the ‘snapd’ package itself. How this information can be retrieved will depend on your distribution:

  • Ubuntu or Debian-based systems: dpkg -l snapd
  • Fedora, RHEL or CentOS-based systems: rpm -qi snapd
  • Arch or Manjaro-based systems: pacman -Qi snapd

Confinement features

When debugging or tracking potential issues with snaps running within a confined environment, the following command can be used to output the sandbox features used by snapd on the system:

snap debug sandbox-features

The following is typical example output from snap debug sandbox-features:

apparmor:             kernel:caps kernel:domain kernel:file kernel:mount kernel:namespaces kernel:network_v8 kernel:policy kernel:ptrace kernel:query kernel:rlimit kernel:signal parser:cap-audit-read parser:cap-bpf parser:qipcrtr-socket parser:unsafe policy:default support-level:partial
confinement-options:  devmode
dbus:                 mediated-bus-access
kmod:                 mediated-modprobe
mount:                layouts mount-namespace per-snap-persistency per-snap-profiles per-snap-updates per-snap-user-profiles stale-base-invalidation
seccomp:              bpf-actlog bpf-argument-filtering kernel:allow kernel:errno kernel:kill_process kernel:kill_thread kernel:log kernel:trace kernel:trap kernel:user_notif
udev:                 tagging

List all packages

Knowing which other snaps are installed, and the applications offered by a specific snap can help with certain issues.

The snap list command will show all installed snaps, for example:

$ snap list
Name                Version            Rev    Tracking          Publisher             Notes
core                16-2.54.2          12603  latest/stable     canonical✓            core
core18              20211215           2284   latest/stable     canonical✓            base
core20              20220202           1336   latest/edge       canonical✓            base
gnome-3-34-1804     0+git.3556cb3      77     latest/stable     canonical✓            -
gnome-3-38-2004     0+git.cd626d1      87     latest/stable     canonical✓            -
gtk-common-themes   0.1-59-g7bca6ae    1519   latest/stable     canonical✓            -
hello-world         6.4                29     latest/stable     canonical✓            -
lxd                 4.22               22306  latest/stable     canonical✓            -
ohmygiraffe         1.1.0a             7      latest/stable     popey                 -
snapcraft           6.0.2              7010   latest/stable     canonical✓            classic
snapd               2.54.2             14549  latest/candidate  canonical✓            snapd
swtpm-mvo           0.1.0              88     latest/edge       mvo                   -
ubuntu-image        2.1+snap3          253    latest/beta       canonical✓            classic
wormhole            0.12.0             349    latest/stable     snapcrafters          -

List snap executables

A snap can include more than one executable or application. Any additional app takes the name of the snap, followed by a dot/period and a suffix for the executable name (<snap-name>.<app>).

All apps provided by a snap can be listed from snap’s binary path, such as /snap/bin on Ubuntu or Debian-based systems. Some distributions, such as Fedora, RHEL and Arch, may use a path other than /snap/bin, such as /var/lib/snapd/snap/bin.

$ ls -l /snap/bin 
total 0
lrwxrwxrwx 1 root root 13 01-31 07:57 hello-world -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 01-31 07:57 hello-world.env -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 01-31 07:57 hello-world.evil -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 01-31 07:57 hello-world.sh -> /usr/bin/snap
[...]
lrwxrwxrwx 1 root root  7 02-02 07:54 lxc -> lxd.lxc
lrwxrwxrwx 1 root root 13 02-02 07:54 lxd -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 02-02 07:54 lxd.benchmark -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 02-02 07:54 lxd.buginfo -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 02-02 07:54 lxd.check-kernel -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 02-02 07:54 lxd.lxc -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 02-02 07:54 lxd.lxc-to-lxd -> /usr/bin/snap
lrwxrwxrwx 1 root root 13 02-02 07:54 lxd.migrate -> /usr/bin/snap
...
lrwxrwxrwx 1 root root 13 2021-06-15  wormhole -> /usr/bin/snap

In the above example output, lxd.lxc indicates that the lxc executable is provided by the lxd snap.

As mentioned earlier, when a snap and application name are identical, there is a <snap-name> with no suffix, such as hello-world in the above example. A telegram-desktop snap would be expected to provide an application named telegram-desktop, for instance, via a symlink called /snap/bin/telegram-desktop.

Retrieve snapd logs

The logs from snapd are extremely useful when trying to work out what a problem might be with a snap’s installation, removal or a refresh.

The logs can be obtained by running:

sudo journalctl -u snapd --no-pager

The output will typically be long and end with the most recent events, which you may want to save to a file and edit to just before a problem first occurred. This would also give you the opportunity to edit any sensitive information you don’t wish to share out of the log.

When a snap won't start

If you have installed a snap that doesn’t appear to start, such as when you click on a launch icon in Gnome Shell and nothing happens, follow these steps to retrieve the most useful details on the issue.

If the failed application is graphical, open a terminal and type echo $DISPLAY:

$ echo $DISPLAY
:0

Next, identify the snap and its application (see above) and attempt to run the snap with logging:

SNAPD_DEBUG=1 snap run <snap-name>.<app>

For example:

$ SNAPD_DEBUG=1 snap run hello-world.hello-world
2022/02/04 10:08:43.792263 tool_linux.go:68: DEBUG: re-exec not supported on distro "arch" yet
2022/02/04 10:08:43.806491 cmd_run.go:437: DEBUG: SELinux not enabled
2022/02/04 10:08:43.806668 tracking.go:46: DEBUG: creating transient scope snap.hello-world.hello-world
...<lots of logs>
DEBUG: read 152 bytes from /var/lib/snapd/seccomp/bpf/global.bin
DEBUG: clearing SYS_ADMIN
DEBUG: execv(/usr/lib/snapd/snap-exec, /usr/lib/snapd/snap-exec...)
DEBUG:  argv[1] = hello-world.hello-world
DEBUG: umask restored to  022
DEBUG: working directory restored to /home/maciek
Hello World!

If you do not see the following two lines then it’s likely that the early snap startup failed, in which case please attach the full log to a new topic in https://forum.snapcraft.io/c/snap.

DEBUG: execv(/usr/lib/snapd/snap-exec, /usr/lib/snapd/snap-exec...)
DEBUG:  argv[1] = <snap>.<app>

In other cases, it becomes more likely that the application failed after being started, in which case see below on permission errors.

Debugging early snap launch issues

The output above indicates that there is no hand-off between the early snap startup process and the actual application. To look into this further, you will need to install the strace diagnostic tool (such as with sudo apt install strace).

With strace installed, issue the following command:

snap run --strace='-vf -s 256' <snap-name>.<app>

The above command will produce output similar to the following when an application crashes, which will need to be included in your failure report:

$ snap run --strace='-vf -s 256' lapce
start to watch path "/home/graham/snap/lapce/x5/.config/lapce/settings.toml"
2022-02-11T11:48:58.405993Z DEBUG hyper::client::connect::dns: resolving host="lapce.github.io"
2022-02-11T11:48:58.476107Z DEBUG hyper::client::connect::http: connecting to 185.199.111.153:443
2022-02-11T11:48:58.478113Z DEBUG druid::localization: available locales [], current en-US
2022-02-11T11:48:58.478155Z DEBUG druid::localization: resolved: [en-US]
2022-02-11T11:48:58.500379Z DEBUG hyper::client::connect::http: connected to 185.199.111.153:443
2022-02-11T11:48:58.521445Z DEBUG hyper::proto::h1::io: flushed 66 bytes
2022-02-11T11:48:58.652028Z DEBUG hyper::proto::h1::io: parsed 23 headers
2022-02-11T11:48:58.652550Z DEBUG hyper::proto::h1::conn: incoming body is content-length (21 bytes)
2022-02-11T11:48:58.656566Z DEBUG hyper::proto::h1::conn: incoming body completed
2022-02-11T11:48:58.656842Z DEBUG hyper::client::pool: pooling idle connection for ("https", lapce.github.io)
2022-02-11T11:48:58.686639Z DEBUG hyper::client::connect::dns: resolving host="raw.githubusercontent.com"
2022-02-11T11:48:58.726092Z DEBUG hyper::client::connect::http: connecting to 185.199.110.133:443
2022-02-11T11:48:58.740189Z DEBUG hyper::client::connect::http: connected to 185.199.110.133:443
2022-02-11T11:48:58.759126Z DEBUG hyper::proto::h1::io: flushed 99 bytes
2022-02-11T11:48:58.944227Z DEBUG hyper::proto::h1::io: parsed 23 headers
2022-02-11T11:48:58.944275Z DEBUG hyper::proto::h1::conn: incoming body is content-length (307 bytes)
2022-02-11T11:48:58.944386Z DEBUG hyper::proto::h1::conn: incoming body completed
2022-02-11T11:48:58.944468Z DEBUG hyper::client::pool: pooling idle connection for ("https", raw.githubusercontent.com)
palette update process stopped
buffer update process stopped
error: exit status 101

Unable to access a file or location

If running a snap, or accessing a location from a snap, produces an error similar to No such file or directory including this location in any forum post report on the issue. If there is a log from the application, attach it.

If you were trying to open a file through a graphical application, indicate whether there was a file open dialog, or any other popups that appeared.

In the case of using graphical applications, make sure you have xdg-desktop-portal installed in your system:

  • Ubuntu or Debian-based systems: dpkg -l |grep xdg-desktop-portal
  • Fedora, RHEL or CentOS-based systems: rpm -qa xdg-desktop-portal\*
  • Arch or Manjaro-based systems: pacman -Qs xdg-desktop-portal

Installation, removal and refresh failures

The snap daemon maintains a log of snap-related changes to the system. This can be output by running snap changes:

$ snap changes
ID    Status  Spawn               Ready               Summary
1573  Done    today at 10:14 CET  today at 10:15 CET  Auto-refresh snaps "lxd", "tpm2-simulator-chrisccoulson"
1574  Done    today at 10:36 CET  today at 10:37 CET  Remove "hello-world" snap
1575  Done    today at 10:37 CET  today at 10:37 CET  Remove "ohmygiraffe" snap
1576  Done    today at 10:37 CET  today at 10:38 CET  Install "spotify" snap

In the above output, the column on the left identifies a specific change and the details of the change can be obtained by issuing snap change <change-id>:

Status  Spawn               Ready               Summary
Done    today at 10:37 CET  today at 10:37 CET  Ensure prerequisites for "spotify" are available
Done    today at 10:37 CET  today at 10:37 CET  Download snap "spotify" (57) from channel "stable"
Done    today at 10:37 CET  today at 10:37 CET  Fetch and check assertions for snap "spotify" (57)
Done    today at 10:37 CET  today at 10:37 CET  Mount snap "spotify" (57)
Done    today at 10:37 CET  today at 10:37 CET  Copy snap "spotify" data
...
Done    today at 10:37 CET  today at 10:37 CET  Connect spotify:icon-themes to gtk-common-themes:icon-themes
Done    today at 10:37 CET  today at 10:38 CET  Setup snap "spotify" (57) security profiles for auto-connections

When reporting such problems, please attach the list of changes and the details of the specific change that failed.

Enable snapd debug logging

If an issue can be repeated predictably, it can help us massively if debug logs are turned on and the issue reproduced with the logs being captured.

To enable debug logs for snapd, enter the following into a terminal:

sudo systemctl edit snapd

The above will open a text editor, and into this you need to paste the following:

[Service]
Environment=SNAPD_DEBUG=1

With this done, save the file, close the editor and restart snapd:

systemctl restart snapd

Now try to perform the operation again and retrieve the logs.

Snap on non-supported distros

It’s great news that you’re trying to get snaps to work on your chosen distro. We’ll try our best to help make them work.

The best place to report issues is https://forum.snapcraft.io/c/snapd/.

When you report problems on a forum post, please make sure the following details are includes:

  • if your distribution is based on another, please tell us which one
  • let us know how you obtained the packages
  • include the contents of /etc/os-release, for example:
    $ cat /etc/os-release 
    NAME="Arch Linux"
    PRETTY_NAME="Arch Linux"
    ID=arch
    BUILD_ID=rolling
    ANSI_COLOR="38;2;23;147;209"
    HOME_URL="https://archlinux.org/"
    DOCUMENTATION_URL="https://wiki.archlinux.org/"
    SUPPORT_URL="https://bbs.archlinux.org/"
    BUG_REPORT_URL="https://bugs.archlinux.org/"
    LOGO=archlinux-logo
    
  • include the output of ls -l /etc/os-release
  • include the journal log from snapd