Skip to content

Troubleshooting

Jump to bottom
nornzach edited this page Aug 10, 2026 · 1 revision

Troubleshooting

Common Issues

Built-in omp not found at startup

Cause: No resources/omp binary in the clone (it's gitignored, ~120 MB).

Fix: Run bun run build:omp (requires the monorepo nested-checkout layout), or drop in a prebuilt sidecar binary at resources/omp.

build-bundled-omp must run inside the omp monorepo

Cause: The GUI repo isn't at packages/gui/ inside a monorepo clone.

Fix: Re-create the nested checkout:

git clone https://github.com/nornzach/oh-my-pi.git omp-monorepo
cd omp-monorepo && bun install && cd packages
git clone https://github.com/nornzach/oh-my-pi-gui.git gui
cd gui && bun install

See Development for details.

replacing stale addon ... version sentinel != <ver>

Cause: Informational message — the cached pi_natives was old; the build script replaced it automatically.

Fix: No action needed.

Failed to download @oh-my-pi/pi-natives-<platform>@<ver>

Cause: That natives version isn't on npm yet.

Fix: Build from source:

bun --cwd=packages/natives run build

(Rust toolchain required), then re-run bun run build:omp.

Intel DMG crashes at launch / sidecar exits immediately

Cause: Wrong-architecture sidecar was packaged.

Fix: Always use bun run package:mac:x64 for Intel builds. The arm64 sidecar will not run on Intel Macs.

macOS blocks first launch

Cause: The build is unsigned.

Fix: Right-click the app -> Open, or go to System Settings -> Privacy & Security -> Open Anyway.

Sidecar crashes repeatedly on startup

Cause: The sidecar binary may be corrupted or wrong architecture.

Fix:

  1. Delete resources/omp (or resources/omp.x64)
  2. Rebuild: bun run build:omp (arm64) or bun run build:omp:x64 (Intel)
  3. Restart the app

If the sidecar still fails, check the log viewer (⌘J -> Logs panel) for the error output.

Session not appearing in sidebar

Cause: Session index may not have picked up the file yet, or the session file is outside ~/.omp/sessions/.

Fix:

  1. Verify the session file exists: ls ~/.omp/sessions/
  2. Restart the app (the session index re-scans on launch)
  3. Check that the session file has a valid 256-byte title slot

Stats dashboard shows no data

Cause: The stats server may not be running, or the app hasn't detected it yet.

Fix:

  1. Verify the stats server is reachable: curl http://localhost:3847/api/stats/overview
  2. The stats server starts when omp runs — start a session first
  3. The stats tab probes lazily on first open; close and reopen it

Commands seem to queue but don't execute

Cause: RPC commands are serialized — only one runs at a time. bash is the only exception (runs in background).

Fix: Wait for the current command to complete. If stuck, press Esc to abort the current turn, which unblocks the queue.

Syncing the monorepo with upstream

Run from the monorepo root:

bash packages/gui/scripts/sync-upstream.sh

If you hit a merge conflict:

SKIP_MERGE=1 bash packages/gui/scripts/sync-upstream.sh

Then resolve conflicts manually and re-run.

Getting Help

Clone this wiki locally