🔧 ZSHAND Troubleshooting¶

📋 Common problems and their fixes. See also README § Troubleshooting.

Run ZSHAND_DEBUG=1 exec zsh to see exactly what loads, how long it takes, and where errors occur. For a full audit: ZSHAND_AUDIT_MODE=1 exec zsh.

📦 Stale bundles¶

Symptom: Startup shows “Bundles: stale (core, functions)” or “bundles stale, run zr”; or behavior doesn’t match your recent edits.

Cause: You edited .zsh files but didn’t rebuild. Production mode loads pre-compiled .compiled/*-all.zwc; if sources are newer than the bundle, the bundle is stale.

Fix:

• Full rebuild: zr or zprime — rebuilds all framework directories.
• Incremental (only stale dirs): zprime --fast or zrf — faster when you only changed one or two dirs.
• Single directory: zr-dir functions or zprime --dir functions — rebuilds only that directory.

Then reload: exec zsh or open a new terminal.

📂 Missing .compiled or bundle failed to load¶

Symptom: Message like “Compiled bundle failed: core-all. Run zr to rebuild.” or “Failed to load: functions.”

Cause: Bundles were never built, were deleted, or are corrupted (e.g. partial write, wrong zsh version).

Fix:

1. Run zr to build all bundles.
2. If that fails with a syntax error, fix the reported file and run zr again.
3. If the framework dir is read-only or you don’t have write permission to */\.compiled/, fix permissions or run from a writable copy.

🏗️ Full bundle or monolithic bundle failed to load¶

Symptom: With ZSHAND_USE_MONOLITHIC=1, startup shows “Full bundle failed to load. Run zfull or zprime --full.” or “Monolithic bundle failed to load. Run zmono or zr.”

Cause: You’re using monolithic mode but the single-file bundle wasn’t built or is missing. Zshrc prefers the full bundle in cache ($ZSHAND_CACHE_DIR/zshand-full.zsh) when present; otherwise it uses the framework-only monolithic bundle ($ZSHAND/.compiled/zshand-all.zsh).

Fix:

• Full bundle (framework + user init.d/rc.d/post.d): Run zfull or zprime --full to build zshand-full.zwc in cache. Requires ZSHAND and ZSHAND_CONFIG_DIR (default ~/.config/zshand).
• Framework-only monolithic: Run zmono or zprime --monolithic to build .compiled/zshand-all.zwc. Then exec zsh.

❌ Syntax errors during compile¶

Symptom: zr or zprime prints “zcompile failed: …” with a file name and line number.

Cause: A .zsh file has a syntax error (unclosed quote, missing done, etc.). Zsh compiles the concatenated bundle; the error message usually points to the right file.

Fix:

1. Open the reported file and fix the syntax (e.g. zsh -n path/to/file.zsh to check that file only).
2. Run zr again.
3. If you can’t find the error, run ZSHAND_DEV_MODE=1 exec zsh — dev mode loads individual files and often gives a clearer error when the bad file is sourced.

💣 Nuclear option: clean rebuild¶

Symptom: Bundles are broken, zr keeps failing, or you want a clean slate.

Fix: Run zrebuild. It (1) syntax-checks all framework .zsh and exits on error, (2) removes all .compiled bytecode and bundles, (3) runs zprime --quiet. Then exec zsh.

🔄 Dev mode auto-rebuild¶

With ZSHAND_DEV_MODE=1 and ZSHAND_DEV_AUTO_REBUILD=1, startup runs a stale check and triggers zprime --quiet if any bundle is stale. Failures are silent (no reload). To see rebuild output, run zr or zprime manually.

⚡ Quick reference¶

🛡️ Safe mode & recovery¶

Symptom: Shell won't start, or framework crashes during initialization.

Fix:

1. Enter safe mode: ZSHAND_SAFE_MODE=1 zsh
2. Safe mode provides a minimal shell with basic PATH — no framework code runs
3. Use the recovery menu to diagnose and fix
4. Common fixes: zr to rebuild, check file permissions, fix syntax errors
5. Exit safe mode: exec zsh

Safe mode can trigger automatically after multiple consecutive startup failures. The failure counter is stored in $ZSHAND_CACHE_DIR/init_failures.

🐌 Slow startup¶

Symptom: Shell takes >100ms to start, or visible delay before prompt.

Diagnosis:

# See per-file timing breakdown
ZSHAND_DEBUG=1 ZSHAND_TIMING_DETAIL=1 exec zsh

# Full profile with graded report
ZSHAND_PROFILE_BUNDLE=1 exec zsh

# Benchmark
hyperfine --warmup 3 'zsh -ic exit'

Common fixes:

• 📦 Not using bundles: export ZSHAND_AUTO_FULL=1 then exec zsh
• 🕐 Slow hooks: export ZSHAND_LAZY_LOAD=1 to defer non-critical hooks
• 🌐 Network in startup: Check for synchronous network calls (ping, curl)
• 📂 Many .zwc missing: Run zprime to compile everything

See PERFORMANCE.md for detailed optimization strategies.

📦 Missing dependencies¶

Symptom: Functions show "jq required" or "command not found" errors.

Fix:

# Check all dependencies at once
auditenv

# Install specific tool
sudo apt install jq        # Debian/Ubuntu
sudo pacman -S jq          # Arch/Manjaro
brew install jq            # macOS

Minimum versions are defined in dependency-version-reqs.toml.

📊 Telemetry not working¶

Symptom: zfail, zlast, zsearch, zpulse show "No telemetry found".

Checklist:

1. ✅ Is LOG_JSON set to true? Check: echo $LOG_JSON
2. ✅ Does LOG_DIR exist? Check: ls $LOG_DIR
3. ✅ Are .jsonl files being created? Check: ls $LOG_DIR/*.jsonl
4. ✅ Is _zrun function loaded? Check: (( $+functions[_zrun] )) && echo yes

Fix: Add LOG_JSON="true" to ~/.config/zshand/env.zsh and exec zsh.

🔗 Related Documents¶