Skip to main content
This guide covers common issues you may encounter when using Warden and how to resolve them.

​
Authentication Issues

​
Claude Code CLI Not Found

Error: 
Claude Code CLI not found on PATH.
Either install Claude Code (https://claude.ai/install.sh) or set an API key.
Solution:
1

Install Claude Code CLI

curl https://claude.ai/install.sh | sh
2

Verify Installation

claude --version
3

Or Use API Key Instead

export WARDEN_ANTHROPIC_API_KEY=sk-ant-...

​
Authentication Failed: Unauthorized

Error: 
Authentication failed: unauthorized
Causes:
  • Invalid or expired API key
  • Claude Code CLI session expired
  • API key lacks necessary permissions
Solution: 
# Re-authenticate
claude login

# Verify authentication
claude --version

# Verify API key is set
echo $WARDEN_ANTHROPIC_API_KEY

# Test API key with curl
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $WARDEN_ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

# Get new API key from console
open https://console.anthropic.com/

​
IPC/Subprocess Errors (EPIPE, ECONNRESET)

Error: 
Error: EPIPE
Claude Code stderr: ...
Cause: The Claude Code CLI subprocess cannot communicate, often due to:
  • Docker/container sandbox restrictions
  • AppArmor/SELinux policies
  • Missing IPC capabilities
Solution: 
# Use direct API authentication in restricted environments
export WARDEN_ANTHROPIC_API_KEY=sk-ant-...
warden scan
Subprocess IPC errors are not retryable. Switch to API key authentication in CI/CD and containerized environments.

​
Analysis Issues

​
No Changes Found

Error: 
No changes found
Causes:
  • No uncommitted changes in working directory
  • All changes are in ignored files
  • Base reference is invalid
Solution: 
# View uncommitted changes
git status
git diff

# View changes in specific range
git diff main...HEAD

# Analyze changes from specific commit
warden scan --base=HEAD~3

# Analyze all changes from main
warden scan --base=main
warden.toml
[defaults]
ignorePaths = [
  "**/node_modules/**",
  "**/dist/**",
  "**/*.test.ts",
]

​
Findings Extraction Failed

Error: 
⚠  2 finding extractions failed
Cause: Warden couldn’t parse JSON findings from model output using regex or LLM fallback. Solution: 
# Run with debug logging to see extraction details
warden scan -vv
Debug Output: 
[debug] Extraction failed: Invalid JSON
[debug] Preview: {"findings": [{"id": "...
[debug] Attempting LLM fallback for extraction repair
[debug] LLM extraction: found 1 finding
Extraction failures are usually transient. Warden automatically retries with an LLM fallback (Haiku) up to 5 times.

​
Failed Hunks

Error: 
⚠  3 chunks failed to analyze
Causes:
  • API rate limits
  • Network timeouts
  • Server errors (5xx)
Solution: 
warden scan -v
Output:
[1/3] src/auth.ts:15-42
  Retry attempt 1/3 after 1.0s (RateLimitError: Request rate limit exceeded)
[1/3] src/auth.ts:15-42
  ✗ Analysis failed after 3 retries: RateLimitError

import { runSkill } from '@sentry/warden';

const results = await runSkill(skill, files, {
  retry: {
    maxRetries: 5,
    initialDelayMs: 2000,
  },
});

# Verify API connectivity
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $WARDEN_ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

​
Configuration Issues

​
Invalid warden.toml

Error: 
Error: Failed to parse warden.toml
Invalid value at path: skills[0].failOn
Cause: Configuration file syntax or validation error. Solution:
src/config/schema.ts
export const WardenConfigSchema = z.object({
  version: z.literal(1),
  defaults: DefaultsSchema.optional(),
  skills: z.array(SkillConfigSchema).default([]),
});
Valid values:
  • failOn: "high", "medium", "low", "off"
  • reportOn: "high", "medium", "low", "off"
  • minConfidence: "high", "medium", "low", "off"
warden.toml
# ❌ Invalid: critical is not a valid severity
[defaults]
failOn = "critical"

# ✅ Valid: use 'high' instead
[defaults]
failOn = "high"

# ❌ Invalid: missing version
[defaults]
reportOn = "medium"

# ✅ Valid: version is required
version = 1
[defaults]
reportOn = "medium"

​
Duplicate Skill Names

Error: 
Error: Duplicate skill names: security-scanning
Cause: Multiple skills with the same name in warden.toml. Solution:
warden.toml
# ❌ Duplicate names
[[skills]]
name = "security-scanning"
paths = ["src/**/*.ts"]

[[skills]]
name = "security-scanning"  # Duplicate!
paths = ["tests/**/*.ts"]

# ✅ Unique names
[[skills]]
name = "security-scanning-src"
paths = ["src/**/*.ts"]

[[skills]]
name = "security-scanning-tests"
paths = ["tests/**/*.ts"]

​
Schedule Skills Missing Paths

Error: 
Error: paths is required for skills with schedule triggers
Cause: Schedule-triggered skills must have explicit paths configuration. Solution:
warden.toml
# ❌ Invalid: schedule skill without paths
[[skills]]
name = "weekly-scan"
[[skills.triggers]]
type = "schedule"

# ✅ Valid: paths specified
[[skills]]
name = "weekly-scan"
paths = ["src/**/*.ts", "lib/**/*.ts"]
[[skills.triggers]]
type = "schedule"

​
Performance Issues

​
Analysis Taking Too Long

Symptoms:
  • Analysis runs for several minutes
  • High token consumption
  • Large files being processed
Solution:
warden.toml
[defaults.chunking]
filePatterns = [
  { pattern = "**/package-lock.json", mode = "skip" },
  { pattern = "**/pnpm-lock.yaml", mode = "skip" },
  { pattern = "**/yarn.lock", mode = "skip" },
]
warden.toml
[defaults.chunking.coalesce]
enabled = true
maxGapLines = 30
maxChunkSize = 8000  # Reduce for faster processing
warden.toml
[runner]
concurrency = 2  # Lower value = less parallel load

[defaults]
batchDelayMs = 1000  # Add delay between batches

# Analyze specific files only
warden scan src/auth.ts src/api.ts

# Analyze specific directory
warden scan src/critical/

​
Large Prompt Warnings

Warning: 
⚠  Large prompt: src/database.ts:1-500 (~25k tokens)
Cause: File chunk exceeds 100,000 characters (~25k tokens). Solution:
src/sdk/types.ts
/** Threshold in characters above which to warn about large prompts (~25k tokens) */
export const LARGE_PROMPT_THRESHOLD_CHARS = 100000;
Large prompts are not errors, but they increase cost and latency. Consider splitting large files or adjusting coalescing settings.

​
GitHub Integration Issues

​
PR Comments Not Appearing

Symptoms:
  • GitHub Action succeeds
  • No PR comments visible
  • Check run shows findings
Solution:
.github/workflows/warden.yml
permissions:
  contents: read
  pull-requests: write  # Required for PR comments
  checks: write         # Required for check runs
Findings below reportOn threshold are not posted as comments:
warden.toml
[defaults]
reportOn = "high"  # Only high-severity findings in PR comments
warden.toml
[defaults]
reportOnSuccess = true  # Comment even with no findings

​
Check Run Failures

Error: 
Error: GITHUB_TOKEN permissions are insufficient
Solution:
.github/workflows/warden.yml
permissions:
  contents: read
  pull-requests: write
  checks: write        # Add this permission
Default GITHUB_TOKEN permissions may be restricted by organization settings. Contact your GitHub admin if issues persist.

​
Debugging Tips

​
Enable Debug Logging

# Full diagnostic output
warden scan -vv
Debug output includes:
  • Prompt sizes and token estimates
  • Cache hit/miss statistics
  • Extraction method (regex vs LLM)
  • Retry attempts and delays
  • Per-hunk timing and costs

​
Check Log Files

# View recent log files
ls -lh .warden/logs/

# Parse most recent log
cat .warden/logs/*.jsonl | tail -1 | jq '.'

# Extract all errors
cat .warden/logs/*.jsonl | jq 'select(.failedHunks > 0)'

​
Reproduce Locally

# Match PR environment
warden scan --base=main

# Use same model as CI
warden scan --model=claude-sonnet-4-20250514

# Enable all logging
warden scan -vv 2>&1 | tee debug.log

​
Report Issues

When reporting issues, include:
1

Warden Version

warden --version
2

Configuration

cat warden.toml
3

Debug Logs

warden scan -vv 2>&1 | tee debug.log
4

Sanitized JSONL Output

warden scan --output=report.jsonl
# Remove sensitive findings before sharing

​
Common Error Reference

ErrorCauseSolution
Claude Code CLI not foundMissing claude binaryInstall CLI or use API key
Authentication failed: unauthorizedInvalid credentialsRe-login or check API key
EPIPE / ECONNRESETIPC failureUse API key authentication
No changes foundNo uncommitted changesCheck git status and base ref
Duplicate skill namesConfig validation errorRename skills to unique names
paths is required for scheduleMissing paths configAdd paths array to skill
Large prompt warningFile chunk too largeAdjust coalescing or skip file
RateLimitErrorAPI rate limitIncrease retry delay, lower concurrency
Findings extraction failedJSON parse errorCheck debug logs, verify model output

​
Getting Help

For questions and support:

Build docs developers (and LLMs) love

Get started for freeTalk to us