Application Note: Running PKCMD‑PI AppImage on Raspberry Pi OS Trixie (32‑bit and 64‑bit)

1. Overview

This application note documents issues encountered when running the PKCMD‑PI AppImage on Raspberry Pi OS Trixie (Debian 13), particularly on 32‑bit ARMv7 systems. Testing confirms that the problem lies with the AppImage runtime rather than with PKCMD‑PI itself.

The note provides symptoms, root cause analysis, and a verified workaround that enables continued operation on affected systems.

---

2. Affected Platforms

• Raspberry Pi OS Trixie 32‑bit (armhf) — AppImage fails to run
• Raspberry Pi OS Trixie 64‑bit (aarch64) — AppImage runs normally
• Debian Trixie on x86_64 — AppImage runs normally

---

3. Symptoms

3.1 Missing FUSE Library

Running the AppImage on 32‑bit Trixie produces:

dlopen(): error loading libfuse.so.2
AppImages require FUSE to run.

Installing the available package:

sudo apt install libfuse2t64

does not resolve the issue.

---

3.2 Exec Format Error

After installing FUSE, the AppImage fails with:

execv error: Exec format error

This indicates that the AppImage loader cannot execute correctly on this OS/architecture combination.

---

4. Root Cause

Testing shows:

• The AppImage loader fails specifically on 32‑bit Raspberry Pi OS Trixie.
• The PKCMD‑PI binary inside the AppImage works correctly when extracted.
• Therefore, the issue is with the AppImage runtime, not PKCMD‑PI.

This behaviour is consistent across multiple test systems.

---

5. Workaround (Verified)

Until a permanent fix is available, PKCMD‑PI can be used on 32‑bit Trixie by extracting the AppImage and running the binary directly.

Step 1 — Extract the AppImage

./pkcmd-pi-armhf.AppImage --appimage-extract

This creates:

./squashfs-root/

---

Step 2 — Install Required Shared Libraries

Copy the bundled .so files into the system library path:

sudo cp ./squashfs-root/usr/lib/*.so* /usr/lib/

Some libraries required by the AppImage runtime are not present in the Trixie repository, so manual installation is currently necessary.

---

Step 3 — Run PKCMD‑PI Directly

Locate the executable:

./squashfs-root/usr/bin/PKCMD-PI

Optionally move it somewhere convenient:

sudo mv ./squashfs-root/usr/bin/PKCMD-PI /usr/local/bin/pkcmd-pi

PKCMD‑PI will now run normally on 32‑bit Trixie.

---

6. Status and Next Steps

The development team is continuing to investigate the AppImage compatibility issue on 32‑bit Raspberry Pi OS Trixie.
A long‑term fix or alternative packaging method will be provided in a future release.

Users encountering additional issues are encouraged to report them so they can be incorporated into the ongoing investigation.

---

7. Summary

• PKCMD‑PI itself runs correctly on 32‑bit Raspberry Pi OS Trixie.
• The AppImage loader fails due to missing or incompatible runtime components.
• Extracting the AppImage and running the binary directly is a reliable workaround.
• A permanent fix is under development.