How to report issues
This guide will walk you through the process of reporting an issue.
Before reporting an issue
- Check if there isn't already an open issue ticket similar to yours; see all issues in postmarketOS repositories.
- Check the Troubleshooting page and the subpages linked there.
- Ask in Matrix/IRC; see Category:Community for a list of help channels. Someone might be able to resolve your issue there; otherwise, the helpful folks there can also help you decide where to file the bug report if you're not sure.
- If you're using postmarketOS edge, check postmarketos.org/edge, which has a list of known issues on the edge branch.
- Try updating your system to make sure the issue hasn't been fixed in a recent update.
Where to report the issue
Depending on the exact scope and nature of the issue, it may be reported in various places.
When in doubt, ask in Matrix/IRC or open an issue in the pmaports repository.
Device-specific issues
Devices not booting, graphical glitches, crashes and general instability, driver bugs and non-working components (apart from those explicitly mentioned as "not working" on your device's wiki page) should be reported in the pmaports repository.
Issues with apps or interfaces/shells
If it's likely that the issue you're having isn't exclusive to postmarketOS and you're running the latest upstream version - in this case, it should be reported to the upstream repositories.
- Phosh: See Phosh repositories; use the issue trackers in the appropriate repository.
- GNOME/GNOME apps: Click the "Report an Issue" button in the About menu - this should take you to the app's repository.
- If there is no such button, find the repository for your app on gitlab.gnome.org (most apps are in the GNOME and World groups; note that using the regular GitLab search will also show forks!).
- GNOME/GNOME apps: Click the "Report an Issue" button in the About menu - this should take you to the app's repository.
- Plasma Mobile/KDE apps: See Plasma Mobile Issue Tracking.
- Sxmo: sxmo-tickets.
- Other projects: find the project website (
apk info <package-name>
can point you in the right direction).
Issues during installation
This depends on the exact way you're installing postmarketOS, and which step you're having trouble with:
- If you find an issue when using pmbootstrap, report it to the pmbootstrap issue tracker.
- If you find an issue with the on-device installer, report it to the postmarketos-ondev issue tracker.
- If you find an issue with the Android recovery installer, report it to the postmarketos-android-recovery-installer issue tracker.
- If your issue is device-specific, such as a flash method failing or the device package being broken, report it to the pmaports repository.
Packages, distro-specific issues
This section refers specifically to the app packages, not the apps themselves; for apps, see the #Issues with apps or interfaces/shells section. |
If an app has missing dependencies, or you can't install it due to conflicts, or seems to be missing some files, you might be dealing with a package issue.
postmarketOS is based on Alpine Linux; as such, before you report a bug, you should first know where the package for the app you're having trouble with is located:
- All device-specific packages (
device-<name>-<codename>
; and kernels other thanlinux-lts
andlinux-rpi
) are in postmarketOS repositories (pmaports). - For other packages, search pkgs.postmarketos.org, then pkgs.alpinelinux.org.
- Note that we carry a few forks of Alpine packages; most of them can be found in the temp directory in pmaports.
Problems with packages that are in Alpine Linux repositories should be reported to the Alpine Linux aports repository. Otherwise, they should be reported in the pmaports repository.
If you encounter a package-related issue in pmbootstrap, report it to the pmbootstrap issue tracker.
Writing a good bug report
The pmaports repository has a template for issues; in general, no matter the project, you should mention the following information:
- The version of postmarketOS you're using (i.e. v23.12, edge, etc.);
- The device you're using and its architecture (you can find this information on the device's wiki page);
- The UI you're using (Phosh, Plasma Mobile, Sxmo, etc. - if in doubt, check Interfaces, which has some screenshots that should help you identify your UI);
- If your report is related to an application, provide the application's version (for GUI apps - find an About dialog, for CLI apps - run
<command> -v
orcommand --version
; for packages in general - checkapk info --installed <package-name>
); - Detailed instructions on how to reproduce the bug, as well as any relevant logs (for apps - try running the affected app from the terminal and see if there's any output there).
Getting logs
- If you're debugging an issue with an application, try running it from the terminal and copy the output.
- On Xorg-based UIs, you may find some logs for launched apps in
~/.xsession-errors
.
- On Xorg-based UIs, you may find some logs for launched apps in
- If the program closes with a "Segmentation fault" or similar, provide a backtrace; see #Capturing a backtrace with gdb.
- If you're debugging an issue related to Phosh or GNOME (for instance, the session crashing or not starting up), see Debugging the GNOME stack.
The project you're submitting a bug report to might have an issue template that can contain other useful tips on how to get relevant log output to provide with your issue.
Capturing a backtrace with gdb
If the application crashes with a "Segmentation fault" or similar error, you may be able to get more information about the crash from a backtrace. Developers often require this information to be able to more easily find the exact issue that causes the app to crash.
To get a backtrace, install the gdb
package, as well as the -dbg
subpackages for the app and the libraries it uses. The -dbg
subpackages contain debug symbols, which are used to identify the name and parameters of a function in GDB's backtraces. Not all packages will have debug symbols available - in that case, you can proceed without them (though you may end up with missing symbols), or try modifying the package to add them: #Adding a -dbg subpackage.
For GTK apps, you'll usually need at least glib-dbg gtk4.0-dbg libadwaita-dbg
and potentially others, depending on the language the app is written in. For QT apps, you'll usually need at least qt6-qtbase-dbg
. If there are any other -dbg
subpackages you'll need to install, you'll spot them when getting the backtrace.
Then, run GDB:
gdb my-app
;gdb --args my-app arg1 arg2
if you need to provide arguments;gdb -p $(pidof my-app)
to connect to a running process. You may need to run this command as root.
The GDB prompt will show up.
GNU gdb (GDB) 14.2 Copyright (C) 2023 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "armv7-alpine-linux-musleabihf". Type "show configuration" for configuration details. For bug reporting instructions, please see: <https://www.gnu.org/software/gdb/bugs/>. Find the GDB manual and other documentation resources online at: <http://www.gnu.org/software/gdb/documentation/>. For help, type "help". Type "apropos word" to search for commands related to "word". (gdb)
In the case of the first two commands, you will need to type run
to get the program to run.
Now, perform the action that causes the program to crash. The program execution should pause, and you should see something like this:
Thread 1 "gnome-shell" received signal SIGSEGV, Segmentation fault. param_spec_pool_hash (key_spec=<optimized out>) at ../gobject/gparam.c:958 warning: 958 ../gobject/gparam.c: No such file or directory (gdb)
(If the program stops, but you do not see a "Received signal" message above the function info, it's usually non-fatal and can be skipped with continue
. If it isn't - read on.)
This tells us that a segmentation fault happened, and it tells us where and in which file it happened. The "no such file or directory" error can be safely ignored - GDB tries to look for the source code in this location, but it's not required.
Now, get the full backtrace by running bt full
:
(gdb) bt full #0 param_spec_pool_hash (key_spec=<optimized out>) at ../gobject/gparam.c:958 key = <optimized out> p = 0x2 <error: Cannot access memory at address 0x2> h = 2759989744 #1 0xb6ab101e in g_hash_table_lookup_node (hash_return=<synthetic pointer>, key=0xbeeca6bc, hash_table=0xb6835b20 = {...}) at ../glib/ghash.c:416 node_hash = <optimized out> (...some more values...) node_key = <optimized out> #2 g_hash_table_lookup (hash_table=hash_table@entry=0xb6835b20 = {...}, key=key@entry=0xbeeca6bc) at ../glib/ghash.c:1483 node_index = <optimized out> node_hash = <optimized out> __func__ = "g_hash_table_lookup" (...and so on...)
If at the bottom you see the following prompt:
--Type <RET> for more, q to quit, c to continue without paging--
then type "c" and hit Return/Enter to display the full backtrace.
If in your backtrace you see ???
instead of the function name:
#0 0xb2506ece in ??? () at /usr/lib/gio/modules/libdconfsettings.so
then you're missing the debug symbols for that library. You can find the main package for the library by copying the library name into the "File" box at pkgs.alpinelinux.org/contents. Find the -dbg
package for this library. If there isn't one, you can skip it, although this will mean that you only get a partial backtrace. Sometimes this is enough for the developer (if the #0 function is visible, then it should be fine), but you may want to get more debug symbols - in that case, see #Adding a -dbg subpackage.
After that, type continue
, and if another backtrace appears, repeat the above steps. Repeat this until the program quits:
Program terminated with signal SIGSEGV, Segmentation fault. The program no longer exists.
Press Return/Enter, then type quit
to exit GDB.
Once you're done, copy the backtraces you just got and attach them to the issue.
Adding a -dbg subpackage
Some packages may not have a -dbg
subpackage. In those cases, you can add one manually by forking the package APKBUILD, modifying the subpackages variable and rebuilding the package with pmbootstrap.
- Run
pmbootstrap aportgen --fork-alpine package-name
(replace package-name with the name of the package you want to build debug symbols for). See pmbootstrap#Building packages. - Go to the directory that the new APKBUILD is located in.
- Open the APKBUILD in your favorite code editor. Find the
pkgrel
variable and increase it by 1. Then, find thesubpackages
variable, and add$pkgname-dbg
:subpackages="$pkgname-dev $pkgname-dbg"
- If there is no
subpackages
variable, add it somewhere around the other variables.
- If there is no
- Run
pmbootstrap build --arch=your-arch package-name
to build the package. Replace your-arch with your device's architecture, package-name with the name of the package you want to rebuild. - Run
pmbootstrap sideload --arch=your-arch package-name package-name-dbg
to sideload the new package to your device.
If you're adding a -dbg
subpackage to a library, you may want to make an upstream merge request to Alpine's aports repo to get the subpackage added there too, so that other people can benefit from it as well.