Troubleshooting

Common problems and how to fix them.

Skills not recognized after install

Symptoms

You type /think and the agent says it does not know that command, or suggests something unrelated.

Cause

The symlinks were not created correctly, or the agent session started before installation finished.

Fix

Run the doctor command and then restart your agent session:

npx create-nanostack doctor
# Fix any issues it reports, then restart the agent

Guard blocks a safe command

Symptoms

Guard blocks a command you know is safe, like deleting a build directory or running a database seed script.

Cause

The command matches a built-in block pattern. Guard uses pattern matching, not semantic analysis.

Fix

Add the command to your custom allowlist:

// .nanostack/config.json
{
  "guard": {
    "allowlist": [
      "rm -rf build",
      "npm run seed"
    ]
  }
}

Artifacts not found by other phases

Symptoms

/review says it cannot find the plan artifact, or /ship reports missing phase artifacts.

Cause

The previous phase crashed before saving its artifact, or you are running in a different working directory.

Fix

Check sprint status and verify your working directory:

sprint.sh status
ls .nanostack/plan/artifact.json

If the artifact is missing, re-run the phase that should have produced it. If the file exists but is not found, make sure all agents are running from the same project root.

Stale lock prevents phase claiming

Symptoms

sprint.sh claim reviewfails with "already claimed" but no agent is running that phase.

Cause

An agent crashed while holding the lock. The lock directory still exists on disk.

Fix

sprint.sh status        # confirms lock is stale
sprint.sh claim --force review

Secret scanner flags false positives

Symptoms

A base64 string in your test fixture or a random ID gets redacted as a suspected secret.

Cause

The string matches the generic pattern for long base64 secrets.

Fix

Add an ignore pattern for your specific format:

// .nanostack/config.json
{
  "secrets": {
    "ignore_patterns": [
      "test_fixture_[a-zA-Z0-9]{32}"
    ]
  }
}

Drift detection too noisy

Symptoms

Every review reports drift because of lock files, generated types, or snapshot files.

Cause

These files change on every build but are never part of the plan.

Fix

// .nanostack/config.json
{
  "drift_ignore": [
    "*.lock",
    "**/*.snap",
    "src/generated/**"
  ]
}

Agent picks the wrong stack

Symptoms

The agent generates React code for a Svelte project, or uses npm when you use pnpm.

Cause

Auto-detection inferred the wrong framework, or your project has config files from multiple frameworks (common in migrations).

Fix

Set the stack explicitly:

// .nanostack/stack.json
{
  "framework": "SvelteKit",
  "package_manager": "pnpm"
}

Project-level config always overrides auto-detection.

Rename did not apply after update

Symptoms

After running /nano-update, your renamed skills revert to their default names.

Cause

The renames.json file was deleted or corrupted.

Fix

Check the file and re-apply:

cat ~/.nanostack/renames.json
# If missing, re-create:
npx create-nanostack rename review=nano-review

/conductor times out waiting for phases

Symptoms

/conductor waits indefinitely for a phase to complete, but the agent running that phase has already finished or exited.

Cause

The agent completed the work but did not run sprint.sh complete <phase> to mark it done.

Fix

Check if the artifact exists and manually mark the phase complete:

ls .nanostack/review/artifact.json   # verify artifact exists
sprint.sh complete review            # mark it done

Getting more help

If your issue is not listed here, check the GitHub issues. If you do not find it there, open a new issue with the output of npx create-nanostack doctor and a description of what you expected versus what happened.