Troubleshooting
Common Navigator issues, each with the symptom you’ll see and the fix.
Restart required after a mid-session update
Symptom: The plugin was updated during a session (nav-start Step 1.5 or claude plugin update), but new or renamed skills aren’t available; old behavior persists.
Why: Claude Code caches skill definitions and paths at session start. When the plugin updates mid-session, the files on disk change (e.g. .../7.0.0/) but the active session still resolves the old cached paths (e.g. .../6.18.1/). This is Claude Code behavior, not a Navigator bug.
Fix: Restart Claude Code. nav-start and nav-upgrade say so after an update for this reason.
Hooks stopped working after an update
Symptom: After updating to a new Navigator version (notably v6 → v7), hook-driven behavior is missing or stale — no session context injection, no workflow gating, or the old hook behavior persists.
Why: The v7 update changed the manifest hook set (nine v6 hook scripts were replaced by the single dispatcher hooks/nav_dispatch.py), and Claude Code caches the registered hooks at session start. The running session keeps the old registration until restarted.
Fix: Restart Claude Code so the new manifest hook set registers. See Version Migration.
Unexpected forced continuation on a read-only turn
Symptom: With stop_completion.continue_enabled on, Navigator occasionally forces a continuation after a turn that didn’t change any code.
Why: Known issue in v7.0.0 (tracked as TASK-72): the stop_completion tree digest can count Navigator-owned state writes (.agent/.nav-runtime-state.json, .agent/knowledge/graph.json) as codebase mutation, so a read-only turn can look unfinished. The feature ships off by default, so this only affects opt-in users.
Fix: Disable stop_completion.continue_enabled in .agent/.nav-config.json, or wait for the fix.
Version drift (project config behind the plugin)
Symptom: The installed plugin is newer than the version referenced in your project’s CLAUDE.md; docs mention features your config doesn’t list.
Why: nav-upgrade updates the plugin binary, but a project’s CLAUDE.md and .nav-config.json are per-project and don’t auto-sync.
Fix: Say “update my CLAUDE.md” (runs nav-sync-claude), which syncs the project config to the installed version while preserving customizations. See Version Migration.
Malformed .nav-config.json
Symptom: Features behave unexpectedly, toggles don’t take effect, or session start errors on config parse.
Why: Invalid JSON (trailing comma, missing brace) or an unknown key.
Fix: Validate the file (python3 -m json.tool .agent/.nav-config.json). Correct the syntax, or regenerate defaults via nav-init. Confirm keys match the documented schema.
Navigator not initialized
Symptom: Skills like nav-stats abort with “Navigator not initialized”; no .agent/DEVELOPMENT-README.md exists.
Why: The project was never bootstrapped, or .agent/ was removed.
Fix: Say “Initialize Navigator” (runs nav-init) to create the .agent/ structure, then start a session normally.
No update notice although a release is out
Symptom: A newer Navigator release exists but session start shows no notice.
Why: The release check is read-only and fails silent: a network failure, a 4-second timeout, a rate-limited GitHub answer, auto_update.enabled: false, or PILOT_EXECUTOR all mean no notice. A failed check records nothing, so the next session start checks again. Within check_interval_hours the last answer is reused. One more cause: with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set, Claude Code refuses every plugin fetch, so the check never answers; auto_update.curl_fallback: true (v8.3.4+) repeats the GET through curl.
Fix: Usually none needed. To update now, run claude plugin update navigator@navigator-marketplace or nav-upgrade, then restart Claude Code. See Auto-Update.
A skill command cannot find the plugin
Symptom: A skill’s shell step fails with No such file or directory under ~/.claude/plugins/cache/navigator-marketplace/navigator/skills/..., or the model guesses a path.
Why: CLAUDE_PLUGIN_ROOT is set for hook commands only; the Bash tool runs skill commands without it. Before v8.3.3 the skills fell back to the plugin cache without its version segment (the cache is .../navigator/<version>/), so the fallback was wrong on every install. Since v8.3.3 the session_start hook writes the root it resolved to ~/.config/navigator/plugin-root on every start, and every skill resolves PLUGIN_DIR as the env var, then that file, then the marketplace clone.
Fix: Update to v8.3.3 or newer and restart Claude Code once so a session start writes the file. cat ~/.config/navigator/plugin-root should print the installed plugin directory.
Symptom: On older installs, the SessionStart hook injects nothing — no Navigator banner despite plugin and config being present.
Why: Earlier versions resolved hook paths via a variable that could expand to empty (CLAUDE_PLUGIN_DIR), or used a shell guard that silently no-opped when the variable was unset. Fixed in v6.15.7 (CLAUDE_PLUGIN_ROOT) after intermediate fixes in v6.14.0/v6.15.1. As of v7.0.0 the individual hook scripts are gone entirely — all events route through the single dispatcher (hooks/nav_dispatch.py), which is fail-open: a dispatch crash never blocks the session, and dispatch health is surfaced.
Fix: Upgrade to the latest version and restart Claude Code so the patched manifest re-registers. See Plugin Operations.