Error Codes

Every error raised by nubos-pilot is a NubosPilotError with a stable code string, a human-readable message, and an optional details object. Callers (workflows, plan-checker, test suites) match on err.code verbatim — never on the message.

class NubosPilotError extends Error {
  constructor(code, message, details) {
    super(message);
    this.name = 'NubosPilotError';
    this.code = code;
    this.details = details;
  }
}

The codes below are grouped by source module. The list is curated from throw new NubosPilotError(...) sites in lib/ and bin/.

Core / lifecycle

Code	Source	Meaning
not-in-project	lib/core.cjs	projectStateDir(cwd) could not find a .nubos-pilot/ ancestor.
lock-timeout	lib/core.cjs	withFileLock could not acquire the lock within timeoutMs.
unknown-command	np-tools.cjs	Top-level dispatch received an unrecognized command name.
init-internal-error	np-tools.cjs	Catch-all wrapper for unexpected throws inside the init dispatcher.

Phase / plan / tasks

Code	Source	Meaning
phase-not-found	lib/phase.cjs	Phase number is malformed or no matching directory exists.
phase-slug-mismatch	lib/phase.cjs	Phase directory exists with a slug that does not match the expected one.
plan-not-found	lib/plan.cjs	parsePlan was given a path that does not exist.
plan-diff-invalid-phase	lib/plan-diff.cjs	np:plan-diff invoked with non-numeric phase.
plan-diff-invalid-plan-id	lib/plan-diff.cjs	Plan-id format violates <NN>-<NN>.
plan-diff-phase-not-found	lib/plan-diff.cjs	Diff target phase directory is missing.
tasks-invalid-frontmatter	lib/tasks.cjs	Task frontmatter missing required field or value.
tasks-invalid-status	lib/tasks.cjs	status value not in the allowed enum.
tasks-invalid-tier	lib/tasks.cjs	tier value not in {haiku, sonnet, opus}.
tasks-invalid-owner	lib/tasks.cjs	owner value not recognized.
tasks-unknown-dep	lib/tasks.cjs	depends_on references a task id that does not exist in the graph.
tasks-cyclic	lib/tasks.cjs	loadTaskGraph detected a dependency cycle.
task-frontmatter-missing	lib/tasks.cjs	Task file has no frontmatter block at all.
task-status-line-missing	lib/tasks.cjs	Task body has no status: line where one is required.
invalid-task-status	lib/tasks.cjs	Status transition violates the lifecycle state machine.
task-not-found	lib/tasks.cjs	Task id not present in the loaded graph.

Agents

Code	Source	Meaning
agent-not-found	lib/agents.cjs	loadAgent(name) could not find agents/<name>.md.
agent-invalid-frontmatter	lib/agents.cjs	Required field missing, or name does not match filename stem.
agent-forbidden-field	lib/agents.cjs	Frontmatter contains model, model_profile, or hooks.
agent-invalid-tier	lib/agents.cjs	tier value not in {haiku, sonnet, opus}.
invalid-tier	lib/model-profiles.cjs	resolve-model was given an invalid tier.
invalid-profile	lib/model-profiles.cjs	resolve-model was given an invalid model_profile.

Git / commit

Code	Source	Meaning
commit-paths-invalid	lib/git.cjs	assertCommittablePaths rejected the input shape.
commit-all-paths-gitignored	lib/git.cjs	All paths in files_modified are gitignored (D-25 hard-fail).
commit-no-paths	lib/git.cjs	Commit invoked with an empty path list.
task-commit-not-found	lib/git.cjs	np:undo-task could not locate the matching commit.
list-task-commits-invalid	lib/git.cjs	git log --grep filter produced an unparseable result.

State / config

Code	Source	Meaning
schema-version-mismatch	lib/state.cjs	STATE.md schema version does not match the runtime expectation.
config-parse-error	bin/np-tools/config.cjs	config.json is not valid JSON.
config-forbidden-key	bin/np-tools/config.cjs	Dotted key path contains a forbidden segment.
config-invalid-key	bin/np-tools/config.cjs	Dotted key segment violates /^[a-zA-Z0-9_-]+$/.

Templates

Code	Source	Meaning
template-not-found	lib/template.cjs	Template file missing.
template-unresolved-var	lib/template.cjs	placeholder has no answer key.

Verify / progress

Code	Source	Meaning
verify-file-unreadable	lib/verify.cjs	Verification target file cannot be read.
verify-phase-dir-missing	lib/verify.cjs	np:verify-work invoked on a phase that has no directory yet.
progress-read-error	lib/progress.cjs	np:progress failed to read a state file.
next-internal-error	lib/next.cjs	Catch-all wrapper for np:next internals.

Undo

Code	Source	Meaning
undo-revert-conflict	lib/undo.cjs	git revert produced merge conflicts.
undo-dirty-tree	lib/undo.cjs	Working tree has uncommitted changes; refuses to revert.
undo-invalid-plan-id	lib/undo.cjs	Plan id does not match <NN>-<NN>.
undo-task-missing-id	bin/np-tools/undo-task.cjs	np:undo-task invoked without a task id.
undo-task-invalid-id	bin/np-tools/undo-task.cjs	Task id format invalid.
checkpoint-orphan	lib/undo.cjs	Found a checkpoint without a corresponding commit.
checkpoint-invalid-task	lib/checkpoint.cjs	Checkpoint operation referenced an unknown task.
checkpoint-invalid-task-id	lib/checkpoint.cjs	Task id format invalid.

Gaps / metrics

Code	Source	Meaning
gaps-invalid-audit-path	lib/gaps.cjs	np:plan-milestone-gaps audit path is malformed.
gaps-audit-not-found	lib/gaps.cjs	Audit file does not exist.
gaps-audit-too-large	lib/gaps.cjs	Audit file exceeds the safety size limit.
gaps-missing-source-phase	lib/gaps.cjs	Audit references a phase that no longer exists.
gaps-no-milestone	lib/gaps.cjs	No milestone scope can be derived from the audit.
metrics-invalid-record	lib/metrics.cjs	Metrics record fails schema validation.
metrics-invalid-phase	lib/metrics.cjs / lib/metrics-aggregate.cjs	Phase number malformed.

Roadmap render

Code	Source	Meaning
roadmap-render-read-error	lib/roadmap-render.cjs	Could not read roadmap.yaml.

Install / payload

Code	Source	Meaning
staging-mkdir-failed	lib/install/staging.cjs	Staging directory could not be created.
staging-clean-failed	lib/install/staging.cjs	Stale staging cleanup failed.
staging-swap-failed	lib/install/staging.cjs	Atomic swap from staging into payload failed.
manifest-build-failed	lib/install/manifest.cjs	Could not enumerate / hash the staged tree.
manifest-invalid-structure	lib/install/manifest.cjs	Manifest JSON shape is wrong.
manifest-parse-failed	lib/install/manifest.cjs	Manifest file unreadable / unparseable.
manifest-write-failed	lib/install/manifest.cjs	Manifest atomic write failed.
manifest-path-traversal	bin/install.js	Manifest path contains .. or is absolute.
target-is-symlink	bin/install.js	Refuses to write into a symlinked payload directory.
backup-source-missing	lib/install/backup.cjs	File to back up does not exist.
backup-refuses-symlink	lib/install/backup.cjs	Refuses to back up a symlink.
backup-rename-failed	lib/install/backup.cjs	Backup rename failed.
agents-md-missing-notice	lib/install/agents-md.cjs	Generated AGENTS.md is missing the managed notice.
agents-md-invalid-input	lib/install/agents-md.cjs	Bad input to generateAgentsMd.
codex-toml-invalid-input	lib/install/codex-toml.cjs	Codex config.toml repair input is invalid.

Workflow-specific

Code	Source	Meaning
eval-review-invalid-arg / eval-review-not-found	bin/np-tools/eval-review.cjs	np:eval-review argument or target invalid.
ai-integration-phase-invalid-arg / ai-integration-phase-not-found	bin/np-tools/ai-integration-phase.cjs	np:ai-integration-phase argument or target invalid.
project-already-initialized	bin/np-tools/new-project.cjs	np:new-project invoked when PROJECT.md already exists.
invalid-slug	bin/np-tools/new-project.cjs	Slug is empty after stripping non-alphanumeric chars.
answers-missing-field	bin/np-tools/new-project.cjs	Interview answer file missing a required key.