Nitpick

Troubleshooting

Common issues and fixes.

Install

claude: command not found when using claude-code provider

Install the Claude Code CLI:

npm install -g @anthropic-ai/claude-code

Or switch to Anthropic direct in nitpick.yaml:

llm:
 provider: anthropic

ANTHROPIC_API_KEY not set

Either export it:

export ANTHROPIC_API_KEY=sk-ant-...

Or add it to .env in the current directory:

echo"ANTHROPIC_API_KEY=sk-ant-..." >> .env

Crawler

Auth fails

Most likely: your login form doesn’t match the default selectors (input[type=email], input[type=password], button with text”sign in”/“log in”/“login”/“continue”), or the login URL in your config is wrong.

Diagnose:

NITPICK_LOG_LEVEL=debug nitpick crawl

Watch for a WARN log of the form Crawling as role failed — since v0.1.3 per-role auth errors are surfaced instead of silently swallowed.

Workarounds, in order of effort:

  1. Remove login_url from your role. For SPAs that auto-redirect or show a login modal on the base URL, leaving login_url unset lets the crawler land on base_url and wait for a password field to appear anywhere.
  2. Pre-populate knowledge-base/auth/<role>.json using a manual Playwright script and skip the crawler’s auth entirely.
  3. Wait for the pluggable auth hook system (planned for a future release).

Crawler finds 0 pages

Check in order:

  1. Auth actually succeeded? knowledge-base/auth/<role>.json must exist AND have non-empty cookies or origins. A file with {"cookies": [], "origins": []} means the SPA wrote its session after the crawler snapshotted — re-crawl with v0.1.3+ which waits for networkidle + revisits the base URL before saving state.
  2. Base URL correct? curl -I $BASE_URL should return something sensible.
  3. App has navigation? <nav>, <aside>, or elements with role="link", role="menuitem".
  4. App uses client-side routing? Nitpick’s SPA mode handles most cases, but not all.

Fallback: specify pages directly, which skips crawler discovery:

nitpick run --scope targeted --url /dashboard --url /tasks

Agent execution

Page test hits max iterations

Default is 100. Indicates the agent is confused about the page or the skill’s phase enforcement isn’t working.

Options:

  1. Lower the limit to fail fast and save money:
llm:
max_iterations: 30

  1. Look at runs/<id>/pages/<page_id>/agent-trace.jsonl: what is the agent repeatedly doing?

  2. Improve the terminal guard list, if the agent is re-opening modals or navigating away accidentally.

Test generation seems flat / missing fields

The Derived UI Model is incomplete. Re-run with exploration-only:

rm -rf runs/<run_id>/pages/<page_id>/
nitpick run --scope targeted --url <page>

Then inspect runs/<new_id>/pages/<page_id>/derived-ui-model/*.model.json.

Providers

Anthropic: 429 rate limit

Nitpick retries automatically (5 attempts, exponential backoff). If you still hit the cap, reduce parallelism:

testing:
 parallel_workers:"25%"

Or upgrade your Anthropic tier.

OpenAI: context_length_exceeded

Your system prompt + messages exceed the model’s context. Workarounds:

  • Switch to gpt-4o (128k context) instead of gpt-4-turbo
  • Lower max_iterations
  • Wait for KB-informed prompt trimming (planned for a future release)

Claude Code provider: claude exited with code 1

Check runs/<id>/pages/<page_id>/claude-stderr.log. Usually a missing skill or a Claude Code update that changed the CLI interface.

Reports

Report shows”0 tests”

Either:

  • Tests were generated but didn’t run (Playwright failed to launch, check test-results/stderr.log)
  • The derived model has no fields[] or actions[]: exploration didn’t cover this page

HTML report doesn’t open

It’s a self-contained file. open runs/<id>/reports/unified-report.html on macOS, xdg-open on Linux, or drag into a browser.

Cost

My bill is higher than expected

Most likely causes (in order):

  1. max_iterations too high: an agent spiraled. Set to 30-50 for CI.
  2. Caching not active: check logs for”cache_read: 0” on iteration 2+. Verify your model supports caching.
  3. Using Opus for everything: switch fast_model to Haiku, and consider Sonnet for main runs.
  4. Full scope too often: use iterative daily, full weekly.

See Cost management for deeper controls.

Still stuck

File a GitHub issue with:

  • Your nitpick.yaml (redacted)
  • The output of NITPICK_LOG_LEVEL=debug nitpick <command>
  • What you expected vs what happened

← Previous

Roadmap

Next →

Changelog