19 Troubleshooting

Troubleshooting

Common issues and how to resolve them.

---

Provider Authentication Errors

Symptom: "authentication failed", "invalid API key", or "unauthorized" errors.

Solutions:

• Verify the correct env var is set for your provider (e.g. ANTHROPIC_API_KEY for Anthropic, OPENAI_API_KEY for OpenAI). Run echo $ANTHROPIC_API_KEY to confirm.
• Check that NITPIK_PROVIDER matches the key you've set. A mismatch (e.g. NITPIK_PROVIDER=openai with only ANTHROPIC_API_KEY set) will fail.
• If using NITPIK_API_KEY as a fallback, ensure it's a valid key for the provider specified in NITPIK_PROVIDER.
• For openai-compatible providers, verify that NITPIK_BASE_URL points to the correct endpoint.

Empty Findings

Symptom: nitpik completes successfully but reports zero findings.

Possible causes:

• Cache hit — the same content was reviewed before. Run with --no-cache to force a fresh review.
• Small or trivial diff — the LLM may genuinely find no issues. This is expected for simple changes.
• Wrong diff base — verify your --diff-base ref exists and has diverged from your current branch. Run git diff main --stat to confirm there are changes.
• Model limitations — some smaller models may miss issues that larger models catch. Try a more capable model.

Findings Outside Diff Scope

Symptom: findings appear on lines you didn't change.

This shouldn't happen in --diff-base, --diff-file, or --diff-stdin modes — nitpik filters findings to diff hunk boundaries after the LLM responds.

In --scan mode, the entire file is in scope, so findings on any line are expected.

If you see out-of-scope findings in diff mode, please report it.

Slow Secret Scanning

Symptom: nitpik takes a few extra seconds before starting the review.

This is expected when --scan-secrets is enabled. The 200+ built-in regex rules are compiled in parallel on the first invocation, typically taking 3–5 seconds. The cost is paid once per run and does not scale with the number of files.

If you don't need secret scanning for a particular run, omit --scan-secrets.

Stale Cache Data

Symptom: nitpik returns outdated findings that don't match the current code.

Solutions:

• Run with --no-cache to force a fresh review.
• Run nitpik cache clear to wipe all cached data.
• Sidecar metadata files older than 30 days are cleaned up automatically, but if you suspect stale data from an old branch, clearing the cache is the fastest fix.

Docker Permission Issues

Symptom: "permission denied" errors when running nitpik in Docker.

Solutions:

• Ensure the mounted volume is readable: -v "$(pwd)":/repo.
• If the repo is owned by a different user inside the container, git may refuse to operate. The official image configures safe.directory for /repo, but custom images may not.
• For cache persistence, mount the cache directory: -v nitpik-cache:/root/.config/nitpik/cache.

CI Token Scope Errors

Symptom: "forbidden" or "insufficient permissions" when using --format bitbucket or --format forgejo.

Bitbucket:

• Inside Bitbucket Pipelines, no token is needed — authentication is automatic.
• Outside Pipelines, the BITBUCKET_TOKEN needs pullrequest and repository:write scopes.
• Create a Repository Access Token under Repository settings → Access tokens.

Forgejo/Gitea:

• The FORGEJO_TOKEN needs at minimum write:repository scope.
• Create a personal access token under User settings → Applications.

Self-Update in Containers

Symptom: nitpik update warns about container environments.

This is intentional. In Docker containers and CI, you should rebuild the image or pin a version in your pipeline instead of self-updating. The binary inside a container image should be immutable.

Pin a specific version:

docker pull ghcr.io/nsrosenqvist/nitpik:0.2.0

Rate Limiting

Symptom: "rate limited" or "too many requests" messages in progress output.

nitpik automatically retries with exponential backoff (up to 5 retries) when rate limited by the LLM provider. If you're consistently hitting rate limits:

• Reduce --max-concurrent (default is 5) to lower parallel LLM calls.
• Use fewer profiles per run.
• Check your provider's rate limit tier and consider upgrading.

Stuck or Hung Reviews

Symptom: a single file × agent task sits on the progress display indefinitely without making progress.

Each review call has a per-attempt timeout (default 300 seconds, set via --timeout <SECONDS>). When the budget elapses, the call is aborted and treated as a retryable error so the standard retry policy kicks in — each retry gets a fresh timeout budget.

If you see frequent timeouts:

• Lower --timeout to fail faster on a hung connection (e.g. --timeout 120).
• Raise it if you legitimately use slow models with many agentic tool calls (e.g. --timeout 600).
• Set --timeout 0 to disable the timeout entirely (not recommended in CI).
• Reduce --max-turns or --max-tool-calls to cap the work a single attempt can do.

Git Errors

Symptom: "not a git repository" or "unknown revision" errors.

• --diff-base requires a git repository. Use --scan for non-git directories.
• Ensure the ref exists: git rev-parse main should succeed.
• In CI, ensure fetch-depth: 0 (GitHub Actions) or git fetch origin <branch> so the base ref is available.

Related Pages

• Installation — install methods and requirements
• LLM Providers — provider setup
• CI/CD Integration — platform-specific setup
• Caching — cache management