Troubleshooting

How-to. Symptom-driven entry point. Find your symptom in the first column, follow the recovery in the second. Error-code reference is the Error Codes page; this page tells you what to do when one of them shows up.

Quickest first

You see / hear	Try first
Anything weird right after install	npx nubos-pilot doctor --fix
The host CLI doesn't expose np:* commands	Re-open the host CLI; managed-block in CLAUDE.md / AGENTS.md is read once at start.
not-in-project thrown anywhere	You are running outside a directory that has .nubos-pilot/. cd into the project root.

Execution / commit problems

Symptom	First diagnosis	Recovery
commit-all-paths-gitignored thrown	Every path in the task's files_modified is gitignored.	Either fix .gitignore or open T<NNNN>-PLAN.md and correct files_modified. Re-run /np:execute-phase.
commit-no-paths	Task's files_modified is empty.	Edit the task PLAN frontmatter to declare paths, then re-run.
Executor hung on a task	Network / model timeout.	/np:resume-work to classify (resume / orphan / clean). If orphan, follow with /np:reset-slice to clear in-flight state.
Executor crashed mid-task, file system left dirty	Working tree has un-committed edits from the crash.	/np:reset-slice (no commit, restores files_modified from HEAD, drops checkpoint).
One committed task is wrong, but the rest of the slice is fine	Need to undo just that commit.	/np:undo-task M001-S001-T0003 — forward git revert, sets task status back to pending.
Whole milestone is wrong, want to start over	Need bulk revert.	/np:undo 1 — reverts every task commit of milestone 1, newest-first. Plans + CONTEXT.md remain.
Verify command keeps failing inside a task	Test or build is genuinely broken.	If the failure is in the task's scope: spawn np-build-fixer (manual) or fix manually then /np:resume-work. If the failure reveals a planning gap: /np:undo-task, edit the task plan, re-run.
pending_todos counter in STATE.md looks wrong	Race or crash during add-todo.	Run /np:state to inspect, then edit STATE.md manually if needed — pending_todos is single-writer-locked but a forced kill mid-write can theoretically skew it.

Plan-phase problems

Symptom	First diagnosis	Recovery
Plan-checker keeps returning issues_found after 2 iterations	Loop is bounded at 2 iterations. The planner couldn't satisfy the checker.	Read M<NNN>-PLAN-REVIEW.md to see the findings. Most often the gap is in CONTEXT — re-run /np:discuss-phase to add the missing decision, then /np:plan-phase --repromote (or a full re-plan).
PHASE SPLIT RECOMMENDED from planner	Milestone is too big for one plan.	Use /np:propose-milestones to re-shape the open pipeline, splitting M<NNN> into two smaller milestones.
np-researcher only writes ## Research Coverage annotation	WebFetch + Context7 both unavailable; the offline-confirm protocol kicked in.	Either configure MCP context7 (see Installation § MCP) or accept the local-only research and proceed.
## CONTEXT CONFLICT from np-architect	Architect detected a decision that would violate M<NNN>-CONTEXT.md or RULES.md.	Re-open /np:discuss-phase <N> with Append-update to either adjust the conflicting decision or remove the architectural ambition.
Scaffolder silently dropped a task	<task> block in slice PLAN missing one of id, depends_on, wave, tier attributes.	Open the slice's S<NNN>-PLAN.md, fix the opening tag, re-run /np:plan-phase <N> --repromote.

Verify / validate problems

Symptom	First diagnosis	Recovery
/np:verify-work reports Fail for an SC	Code shipped doesn't satisfy the success_criterion.	Read M<NNN>-VERIFICATION.md to see the evidence cite. Three options: fix in next milestone, add a new task to current milestone, or accept and update the CONTEXT to defer.
Verifier classifies several SCs as Needs-User-Confirm	Subjective/UX criteria need human eye.	Pass-2 askuser gate fires automatically. Answer Pass / Fail / Defer per SC.
/np:validate-phase reports many UNDER_SAMPLED	Tests exist but don't directly observe the requirement.	Read the ## Remediation Guidance section in M<NNN>-VALIDATION.md for suggested test names and assertion shapes. Add tests; re-run validate.
Verify says Pass, validate says UNCOVERED	Code works but no test covers it — silent regression risk.	Same as above — add direct test assertions. Don't merge until both agree.

Worktree problems (workflow.worktree_isolation: true)

Symptom	First diagnosis	Recovery
FF-merge fails at slice end with non-FF	The base branch advanced while the slice ran.	Decide whether to rebase the slice branch (manually, then re-run worktree-ff-merge) or accept the divergence and merge manually. ADR-0008 D-8.7 surfaces this rather than silently rewriting commits.
Stale worktree directory under .nubos-pilot/worktrees/	A previous slice crashed without cleanup.	node np-tools.cjs worktree-list to enumerate; worktree-remove --force <slice-id> to clean up.
.nubos-pilot/worktrees/ not gitignored	Pre-flight check fails before any worktree is created.	Add .nubos-pilot/worktrees/ to .gitignore and re-run.

Install problems

Symptom	First diagnosis	Recovery
target-is-symlink	Payload directory is a symlink — refused by the installer.	Inspect .claude/nubos-pilot/; replace the symlink with a real directory or move the payload destination.
manifest-path-traversal	Manifest contains a .. or absolute path.	Likely a corrupted payload. npx nubos-pilot uninstall (preserves Project-State) and reinstall.
Codex [features] table broken in ~/.codex/config.toml	Known Codex-side bug.	npx nubos-pilot doctor --fix repairs it idempotently.
npx nubos-pilot update fights with hand-edits in payload files	The diff said "user-modified" and backed up to .bak.<n> before overwriting.	Compare the .bak.<n> against the new file and merge by hand.

Doctor checks

npx nubos-pilot doctor runs through:

1. Manifest hash — every shipped file matches its recorded SHA-256.
2. Version mismatch — installed payload version ≠ package.json version.
3. Hooks presence — declared hook files exist on disk.
4. Codex trapped-features — known broken ~/.codex/config.toml table.
5. Askuser runtime — prompt capability is callable.
6. Codebase docs freshness — modules whose hashes drifted since /np:scan-codebase.
7. Milestone layout — every roadmap.yaml entry has a matching milestones/M<NNN>/ directory; legacy phases/ flagged.

--fix applies the auto-safe ones (1, 4 mostly).

When in doubt

• /np:state — what does the tool think the current milestone/task is?
• /np:dashboard — visual overview of every slice's task statuses.
• node np-tools.cjs config-get <key> — what's actually in config.json?
• node np-tools.cjs detect-runtime — which runtime is the host resolving to?
• git log --oneline | grep '^[a-f0-9]\{7,\} task(' — every per-task commit, in chronological order.

If everything else fails: the Error Codes reference lists every NubosPilotError code with its source module. Match on err.code, not on the message.