User:Knuxfanwin8/Draft:Troubleshooting

From postmarketOS
🚧 This page is a work-in-progress. Some information contained within may be inaccurate or incomplete.


In particular: This is a work-in-progress re-organized page for Troubleshooting. Some guiding thoughts and principles for this one follow:

Target audience

The troubleshooting page is likely to be frequented by one of three kinds of users:

  • People using pmbootstrap either for development or installing postmarketOS; pmbootstrap prints a link to the troubleshooting page, so it would be nice to get them to a page that has pmbootstrap-specific issues.
    • Within this category there are people working on new device ports, who need advice on not just pmbootstrap issues, but some on-device issues common for new ports.
  • People trying to troubleshoot issues with their postmarketOS installs, who get to the troubleshooting page either from postmarketos-welcome or by finding the link on the wiki.

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:

  • On-device users should be guided to e.g. the How to report issues page, alongside with some notes on e.g. getting boot logs for debugging early boot issues (what Caleb's been adding to Troubleshooting), plus common on-device errors and pitfalls (e.g. maybe worth mentioning the dreaded "File not found" that happens when you try to run a glibc-compiled program...)
  • pmbootstrap users and developers have different debugging needs - we need to explain how to use pmbootstrap log, pmbootstrap update, pmbootstrap zap to fix issues, and have some ready answers for common errors. Maybe mention when to report issues to the pmbootstrap repo, and when to report them to pmaports.

Sometimes, the issues described for the two overlap - for example, since both pmbootstrap and on-device users will inevitably end up using apk at some point, they could hit issues like e.g. "unable to select packages".

The Troubleshooting pages contain tips for troubleshooting various problems, as well as solutions for commonly-encountered issues and errors.

Icon-numix-light-applications-engineering.svg

Development issues

Note If you get stuck or need assistance, you can join our Matrix/IRC chats.
Hint 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 of 172.16.42.XXX.
    • If you see a device in ip a, check if you can connect to it with ssh 172.16.42.1, or telnet 172.16.42.1.
  • Report an issue to the pmaports repo. If you managed to connect to the device, attach logs from dmesg and logread (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.