User:Knuxfanwin8/Draft:Troubleshooting
🚧 | This page is a work-in-progress. Some information contained within may be inaccurate or incomplete.
Target audienceThe troubleshooting page is likely to be frequented by one of three kinds of users:
So far, the Troubleshooting page tries to cater to all of them, but I'm not convinced it's a viable solution. Both users have different needs:
Sometimes, the issues described for the two overlap - for example, since both pmbootstrap and on-device users will inevitably end up using |
The Troubleshooting pages contain tips for troubleshooting various problems, as well as solutions for commonly-encountered issues and errors.
If you get stuck or need assistance, you can join our Matrix/IRC chats. |
You can browse the different sections of this page by clicking the relevant links in the table of contents, located on the sidebar. |
This page provides an overview of methods for troubleshooting on-device issues, with a focus on existing ports.
If you are looking for support for developing your own port, or if you're dealing with a more technical issue with an unmaintained port and need to fix it, see Troubleshooting/Development issues.
General troubleshooting steps
Looking through reported issues
Most issues in postmarketOS are reported to the pmaports issue tracker. It's worth checking if somebody hasn't already encountered the same issue as you.
If your issue hasn't been reported yet, you are encouraged to report it; this way, developers can be notified about issues they may have missed, and other users will have an easier time troubleshooting their devices. For an overview of where and how to report issues, as well as what information to include, see How to report issues.
Gathering information about the issue and its causes
TODO: Does the issue happen after a fresh install, or after an upgrade, package installation etc? upgrade logs, recovering from a broken upgrade, etc.
Getting logs
TODO: logread, /var/log, running from terminal (for apps), etc.
Boot issues
The exact methods of troubleshooting non-booting devices depend on the stage of the boot process that it fails on.
Device is stuck on manufacturer logo / doesn't get to postmarketOS boot splash
- Check if the display is listed as working on your device's wiki page.
- Plug the device into your computer. Are there any messages in
dmesg
when you plug it in? You should see something like this:
usb 3-4: new high-speed USB device number 2 using xhci_hcd usb 3-4: New USB device found, idVendor=XXXX, idProduct=XXXX, bcdDevice= X.XX usb 3-4: New USB device strings: Mfr=1, Product=2, SerialNumber=3 usb 3-4: Product: (DEVICE NAME HERE) usb 3-4: Manufacturer: (MANUFACTURER HERE) usb 3-4: SerialNumber: postmarketOS usbcore: registered new interface driver cdc_ether cdc_ncm 3-4:1.0: MAC-Address: XX:XX:XX:XX:XX:XX Cdc_ncm 3-4:1.0 usb0: register 'cdc_ncm' at usb-0000:2d:00.3-4, CDC NCM (NO ZLP), XX:XX:XX:XX:XX:XX usbcore: registered new interface driver cdc_ncm usbcore: registered new interface driver cdc_wdm usbcore: registered new interface driver cdc_mbim
- If a device appears, check if it establishes a network connection with your computer. Run
ip a
- you should see a "usb0" or similar device, with IP addresses in the range of172.16.42.XXX
.- If you see a device in
ip a
, check if you can connect to it withssh 172.16.42.1
, ortelnet 172.16.42.1
.
- If you see a device in
- Report an issue to the pmaports repo. If you managed to connect to the device, attach logs from
dmesg
andlogread
(if available).
Device is stuck on postmarketOS boot splash
"ERROR: Boot partition not found, retrying..."
This usually happens when postmarketOS cannot find the partition that the rootfs has been installed to. The "boot partition" in this message refers to the boot subpartition of the pmOS partition (see Partition layout).
Make sure that the rootfs has been flashed correctly, reflash if needed.
If you flashed the rootfs to an SD card or another external storage medium, make sure the correct medium is plugged into the device. If you're using a pre-built image, some devices may need additional steps to prepare the system image before flashing the standard image to an SD card - check your device's wiki page.
Connecting to the device to get logs
TODO: the boot mass device steps from Troubleshooting, ssh or telnet, Inspecting the initramfs, stepping through the boot process
UI does not boot, device is stuck on TTY "login:" screen
TODO: logread, tinydm vs lightdm vs gdm, Debugging the GNOME stack
Application issues
TODO: running from terminal, gdb, How to report issues
"File not found" while running binary from terminal, despite it being there
This is caused by the binary being linked to a library that isn't installed, and usually appears when trying to run a binary compiled for glibc (the GNU libc) instead of musl (the libc that Alpine Linux/postmarketOS uses).
If it's the latter, try to recompile the software yourself, or ask the developer for a version of the binary compiled against musl, or install gcompat
.