Troubleshooting

Solutions for the most common issues encountered when using Technical Debt Radar.

---

False Positives

A violation is flagged but the code is intentionally written that way

Add an exception in radar.yml:

exceptions:
  - rule: sync-fs-in-handler
    file: src/health/health.controller.ts
    expires: "2026-12-31"
    reason: "readFileSync used for small config file at startup, cached after first call"

Exceptions require:

• rule: The rule ID (see Violation Catalog)
• file: File path (supports glob patterns like src/scripts/**)
• expires: Expiration date (forces periodic review)
• reason: Why the exception exists (appears in PR comments)

Circular dependency detected but modules are designed to cross-reference

If two modules intentionally share a bidirectional relationship, use an exception:

exceptions:
  - rule: circular-dependency
    file: src/orders/**
    expires: "2026-12-31"
    reason: "Orders and Inventory have an intentional bidirectional dependency via events"

Alternatively, refactor to use an event-based pattern to eliminate the cycle.

Performance violation on a table that is actually small

Ensure you have declared accurate data volumes in radar.yml:

data_volumes:
  users: M        # 10K-100K rows
  config: S       # < 10K rows (won't trigger performance blocks)
  audit_logs: XXL # 50M+ rows

If no volume is declared for a table, Radar defaults to M (medium) sizing.

---

Scan Issues

Scan not detecting my files

Check your stack configuration. Radar only analyzes files matching the declared language:

stack:
  language: TypeScript  # Analyzes .ts and .tsx files
  framework: nestjs
  orm: prisma

If you have JavaScript files that should also be analyzed, check that your glob patterns include them.

Check file paths. Radar analyzes changed files in a PR. If files are not in the diff, they are not analyzed. For a full codebase scan, use radar scan from the CLI.

Check .gitignore. Files ignored by git are not included in PR diffs and will not be analyzed.

Scan times out

Default timeout is 30 seconds for PR analysis and 15 minutes for first scans.

For large codebases (1000+ files):

• Ensure only relevant source files are analyzed by configuring layers and modules paths precisely
• Exclude test files, generated files, and vendor directories from analysis scope
• Consider splitting into multiple repositories if the monorepo is very large

For first scans:

• First scans analyze the entire codebase and may take several minutes for large projects
• The 15-minute timeout (FIRST_SCAN_TIMEOUT_MS) can be adjusted if needed

Duplicate violations appearing

This can happen when:

1. The same file is included in multiple module paths --- ensure module paths do not overlap
2. Cross-file analysis re-flags a violation already found by deterministic analysis --- this is deduplicated automatically, but check if you see duplicates after an upgrade

---

GitHub Integration

GitHub Action not posting PR comments

1. Check permissions. The GitHub App or Action needs pull-requests: write and statuses: write permissions.

2. Check the webhook configuration. In your GitHub App settings, verify:

   • Webhook URL points to https://api.radar.dev/v1/webhooks/github
   • Pull request events are enabled
   • The webhook shows successful deliveries (not 4xx/5xx errors)

3. Check the webhook secret. The GITHUB_WEBHOOK_SECRET environment variable must match the secret configured in the GitHub App settings.

4. Check the GitHub Action logs. Run the action with debug logging:

- uses: radar-dev/radar-action@v1
  with:
    api-key: ${{ secrets.RADAR_API_KEY }}
  env:
    ACTIONS_STEP_DEBUG: true

Status check stuck on "pending"

This means the analysis was queued but never completed. Check:

1. Redis connectivity. The BullMQ worker needs Redis to process jobs.
2. Worker process running. Ensure the API server's worker process is running and consuming from the analysis queue.
3. Job errors. Check the API server logs for analysis job failures.

"Invalid signature" errors on webhook

1. Verify the GITHUB_WEBHOOK_SECRET matches the GitHub App configuration
2. Ensure the raw body is available (NestJS requires rawBody: true in NestFactory.create)
3. Check that no middleware is modifying the request body before the webhook controller

---

GitLab Integration

GitLab webhook not triggering

1. Verify the webhook URL in GitLab project settings: Settings > Webhooks
2. Ensure "Merge request events" is checked
3. Check the webhook delivery log in GitLab for errors
4. Verify the secret token matches your configuration

---

CLI Issues

radar init not detecting my framework

radar init detects frameworks by analyzing package.json dependencies. Ensure:

1. Dependencies are installed (npm install or equivalent)
2. The framework package is in dependencies or devDependencies:
   • NestJS: @nestjs/core
   • Express: express
   • Fastify: fastify
   • Koa: koa
   • Hapi: @hapi/hapi

If auto-detection fails, specify the framework manually:

radar init --framework nestjs --orm prisma

radar scan shows no violations

1. Check the current directory. Run radar scan from the project root where radar.yml is located.
2. Check the policy. A minimal radar.yml with only stack configuration and no layers or rules will not detect architecture violations.
3. Run with verbose mode:

radar scan --verbose

This shows which files are analyzed, which rules are applied, and timing information.

radar gate always passes

The gate checks debt_delta_score against the threshold. If the score is 0:

• Verify violations are being detected with radar scan
• Check radar.yml gate configuration:

gates:
  block_merge:
    - metric: debt_delta_score
      operator: ">"
      value: 15

---

Dashboard Issues

Dashboard shows no data

1. Check the repository connection. Navigate to Settings and verify the repository is linked.
2. Trigger a first scan. New repositories need an initial scan to generate baseline data.
3. Check the API connection. Open browser developer tools and verify API requests to /api/repos are returning data.

Architecture graph not loading

The architecture graph requires:

1. Pro plan or above (feature is gated)
2. At least one completed scan with import graph data
3. Defined layers and modules in radar.yml

---

Credit Usage

Credit usage higher than expected

AI credits are consumed by:

Operation	Credits
AI scan summary	5
AI cross-file analysis	10-15
AI fix suggestion (per violation)	3
AI PR comment enrichment	5

To reduce credit usage:

• Disable AI features you do not need in radar.yml
• Use deterministic-only mode for most PRs and enable AI only for critical reviews
• AI analysis is optional --- the deterministic analyzer catches all violations without credits

Credits not resetting monthly

Credits reset on the subscription billing date, not the calendar month. Check GET /credits/org/:orgId for the resetsAt date.

---

Debugging

Enable verbose logging

CLI:

radar scan --verbose

API server:

NODE_ENV=development npm run dev

The development mode enables detailed NestJS logging including:

• Incoming requests and responses
• BullMQ job processing events
• Database query logging (Prisma)
• Webhook verification results

Check analysis job status

# Via CLI
radar status <run-id>

# Via API
curl https://api.radar.dev/v1/api/repos/<repo-id>/prs \
  -H "Authorization: Bearer $TOKEN"

---

Reporting Issues

If you encounter a bug:

1. Reproduce with --verbose mode and capture the output
2. Include your radar.yml (redact sensitive paths if needed)
3. Note the rule ID of any incorrect violation
4. Include the code snippet that triggers the false positive/negative
5. Open an issue at the project repository or contact support