Troubleshooting

Troubleshooting

---

AppImage won't run — dlopen(): error loading libfuse.so.2

Cause: AppImages require FUSE 2 to mount their SquashFS payload.

Fix:

# Debian / Ubuntu 24.04+
sudo apt install libfuse2t64

# Older Debian / Ubuntu
sudo apt install libfuse2

---

MeCab not found / furigana silently skipped

Symptom: Log shows no [furigana] mecab — lines, or results have no [かんじ] annotations.

Fix:

sudo apt install mecab mecab-ipadic-utf8

Verify MeCab works:

echo "食べ物" | mecab

If you want a higher-quality dictionary (NAIST jdic — more vocabulary than IPAdic):

sudo apt install mecab-naist-jdic

mecab-furigana-rs auto-discovers the best installed UTF-8 dictionary. No config change needed.

---

HUD not appearing

Step 1 — check if the HUD process is running:

lsof -i :7331

If nothing is listed, the HUD failed to spawn.

Step 2 — check the lenzu log for spawn errors:

lenzu: could not spawn HUD (lenzu-hud or dev tree): No such file or directory

This means $APPDIR/usr/bin/lenzu-hud wasn't found. Only occurs if running a broken AppImage build; v0.1.6+ fixes this.

Step 3 — check if a compositor is running: Electron's transparent: true requires an X11 compositor. Without it the HUD window appears opaque black. Enable your compositor and relaunch Lenzu.

Note: Older Electron (36–41) had a ghost-pixel issue with xfwm4 compositing. Updating to Electron 42+ fixes it — no separate compositor (picom) needed.

Step 4 — check if Lenzu is running without overlay_enabled:

grep overlay_enabled lenzu_config.json

If false, no HUD is spawned by design.

---

HUD disappears mid-session (GPU crash)

Symptom: Log shows errors like:

LaunchProcess: failed to execvp: /proc/self/exe
GPU process launch failed: error_code=1002
FATAL: GPU process isn't usable. Goodbye.

Cause: Chromium's GPU and zygote subprocesses try to re-execute themselves via /proc/self/exe, which resolves to the AppImage AppRun entry point. This fails inside the FUSE mount.

Fix: Already applied in v0.1.15 — the lenzu-hud wrapper now passes --disable-gpu, forcing Chromium to use software rendering. Upgrade to v0.1.15 or later.

---

ONNX model not found — text detection disabled

Symptom: Log shows:

[jp_detect] text_detection_model is configured but ... text detection disabled

or:

[OCR] text detection model 'assets/...' not found in CWD or standard data dirs

Fix: Install the DBNet model sidecar:

# From the bundle (recommended):
LENZU_RELEASE_BASE=file://$(pwd) ./lenzu-appimage-installer.sh

# Or manually: extract lenzu-models-dbnet-*.tar.xz to ~/.local/share/lenzu/
tar -xJf lenzu-models-dbnet-*.tar.xz -C ~

The model resolves from these paths in order:

1. assets/stabrise-text_detection_dbnet_ml_v02_model.onnx (relative to CWD)
2. ~/.local/share/lenzu/models/
3. /usr/share/lenzu/models/
4. /usr/local/share/lenzu/models/

---

manga-ocr models not found — local OCR disabled

Symptom: Log shows local manga-ocr loaded is absent, and every shift-click goes straight to the LLM.

Fix: Install the manga-ocr sidecar:

LENZU_RELEASE_BASE=file://$(pwd) ./lenzu-appimage-installer.sh
# or:
tar -xJf lenzu-models-manga-ocr-*.tar.xz -C ~

Models should be at ~/.local/share/lenzu/manga-ocr/encoder_model.onnx.

---

"Already running" on startup — stale PID file

Symptom:

lenzu: already running (pid 12345) — exiting

But Lenzu isn't actually running (e.g. it crashed previously).

Fix:

rm /dev/shm/lenzu/lenzu.pid

The PID file is automatically cleaned up on normal exit, but a crash or SIGKILL leaves it behind. Lenzu checks whether the PID is alive before blocking — if the stale PID has been reused by another process, remove the file manually.

---

Bus error (SIGBUS) on Shift+H

Symptom: Lenzu crashes with Bus error immediately after [OCR] cancel: help-dialog.

Cause: Intermittent FUSE mount fault — GTK loads theme/icon assets from the AppDir when opening the help dialog; a momentary FUSE hiccup causes SIGBUS on those memory-mapped pages. Self-heals on restart.

Fix: Restart Lenzu. If it recurs frequently, file a report at issue #13 with the frequency.

---

OCR always falls through to remote LLM — no local pipeline

Symptom: Every capture shows [OCR] all local backends failed — trying free remote or similar. Slow results.

Checklist:

1. Is ollama running? curl http://localhost:11434/health
2. Is the model pulled? ollama list — should show glm-ocr (or your configured model)
3. Is DBNet enabled? Log should show text detection enabled (...). If not, see ONNX model not found above.
4. Try --furigana_only for offline-only mode: lenzu --furigana_only

---

HUD text color / font size wrong (cyan, tiny)

Cause: An April 2026 schema migration commit renamed hud_config.json keys from camelCase to snake_case, activating wrong values that had always been in the file but were previously silently ignored.

Fix: Upgrade to v0.1.9 or later. All three values (color, font size, opacity) are restored to correct defaults.

---

Collecting debug information

When filing a bug, include:

lenzu --version
cat /etc/os-release | grep PRETTY_NAME
uname -r
dpkg -l mecab mecab-ipadic-utf8 2>/dev/null | grep ^ii
lsof -i :7331

And the full stderr output from lenzu --furigana_only for the session where the issue occurred.