Help

Troubleshooting

Most problems are a PATH, a platform requirement or an extension. Start by checking that Pi-Bolt runs its compiled code, then find your symptom below.

Check the compiled code#

$ BUN_STATIC_HEAP_VERBOSE=1 pi-bolt --version
[aot] image of 42467328 bytes mapped, 35635200 of them code
[static heap] 94109736 bytes in executable, mapped: true
[aot] image registered: true
1.1.0 (Pi-Bolt 0.8.0, linux-x64, JIT off)

image registered: true means Pi runs its ahead-of-time compiled code. Without the variable, a healthy executable prints nothing extra.

Notices at startup#

When the compiled code cannot be used, Pi-Bolt prints one line and runs Pi from bytecode. Pi works correctly, but starts more slowly and uses more CPU.

pi-bolt: the executable's ahead-of-time compiled code is not used (<reason>); running from bytecode

Reason	Cause and fix
`the address space for it is not available`	An address-space limit (`ulimit -v`, `RLIMIT_AS`, or `vm.overcommit_memory=2`). The compiled code needs about 10 GB of virtual address space, reserved, not used. Raise or remove the limit.
`this CPU lacks an instruction set the code was compiled for`	The Linux `x64` build on a CPU without AVX2. Install the `x64-baseline` build (`PIBOLT_VARIANT=x64-baseline`).
`the image is not one for this engine`, `the image could not be mapped executable`, `the prebuilt heap could not be mapped`	A damaged executable, or a system that forbids executable file mappings. Reinstall and check `SHA256SUMS`. Report it if it persists.
`the executable could not be loaded where its prebuilt heap expects it`	macOS only. Report it, with `sw_vers` and how Pi-Bolt was started.

One failure is fatal instead: the executable's ahead-of-time code image was rejected by the engine. It should not happen with a release build. Run with BUN_AOT=0 and report it.

Common problems#

`pi-bolt: command not found`#

~/.local/bin is not on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile. On Windows, open a new terminal after installing, or run the installer again and let it add Pi-Bolt to your PATH.

`GLIBC_2.xx not found`, or `No such file or directory` on Linux#

The system uses musl (Alpine) or a glibc older than 2.17. Pi-Bolt needs glibc 2.17 or later.

`Illegal instruction`#

The CPU has no SSE4.2 (older than Intel Nehalem, 2008, or AMD Bulldozer, 2011). No Pi-Bolt build runs on it.

`bun:ffi requires the JIT`#

An extension uses bun:ffi (for example pi-fff). Install the JIT build: see Switch builds.

An extension is slow#

On the default build, extensions loaded at run time are interpreted. Use the JIT build, or compile the extension in.

Subagents run stock Pi, or fail to start#

The extension starts subagents with the pi command. Point it at pi-bolt: see Extensions that start Pi.

A theme, HTML export or image tools are missing#

The executable was moved away from the files around it. Keep the installed folder together, and link to the executable instead of copying it.

Startup is slower than expected#

Check that the compiled code is used (above). Run with PI_TIMING=1 to see slow extension factories. The first start after a reboot or an install also reads the executable from disk.

The screen draws wrongly while scrolling#

Start Pi-Bolt with PI_TUI_SCROLL_ROWS=0. It redraws changed rows instead of scrolling them, for terminals that do not scroll a region of the screen correctly.

macOS#

Killed at once (`zsh: killed`), or "cannot verify the developer"#

The executable is quarantined: it was downloaded with a browser. Install with the installer or npm, which do not quarantine, or remove the attribute: xattr -dr com.apple.quarantine pi-bolt-darwin-arm64.

"Pi-Bolt runs on Macs with Apple silicon only"#

There is no build for Intel Macs. On an Apple silicon Mac, a terminal running under Rosetta still installs the ARM64 build, which runs natively.

`pi`, `pi-bin` and `pi-spawn`#

In the macOS build, pi is a small launcher, pi-bin next to it is the Pi-Bolt executable, and pi-spawn starts the programs Pi runs. Link pi rather than copying it: it starts the pi-bin next to its real path.

Re-signing the executable#

codesign may re-sign pi-bin. With the hardened runtime (-o runtime), add the entitlement com.apple.security.cs.disable-library-validation; without it, Pi-Bolt runs from bytecode with one notice. The JIT build also needs com.apple.security.cs.allow-jit.

Reporting a problem#

First, check whether the problem is Pi-Bolt's:

If it also happens with BUN_AOT=0 pi-bolt and with stock Pi, it is Pi's: report it to Pi.
If it only happens with Pi-Bolt, open an issue with:
- the output of BUN_STATIC_HEAP_VERBOSE=1 pi-bolt --version;
- your system: on Linux, the distribution, ldd --version | head -1 and the CPU model; on macOS, sw_vers and sysctl -n machdep.cpu.brand_string; on Windows, the Windows version and CPU;
- whether it also happens with BUN_AOT=0 pi-bolt.

A crash#

When Pi-Bolt crashes, it prints "Pi-Bolt has crashed", a few lines about the system, and a link that starts with https://pi-bolt.opensec.in/crash/. The link holds an encoded stack trace and nothing else: no file names, paths or data of yours. Include it in the issue, with what you were doing. The maintainers decode it against that release's symbols.