Troubleshooting — what to do when something breaks

For: all
Tier: free+
Time: ~5 min

Why you'd do this

Compliance work is procedural — when a tool errors mid-flow, the instinct is to retry and hope. This chapter lists the failure modes that show up most often, with verbatim error strings so search lands you in the right resolution.

Before you start

• Use Ctrl+F / Cmd+F to find the exact error string you saw — most errors appear here verbatim
• If the error has an error_id (format: err_NNNNNNNNN), keep that for support — server-side stack trace is keyed by it

Step 1

MCP connection failures

These show up in your IDE's MCP tool panel, usually as the response body of cl_connect / cl_sync / cl_disconnect.

| Error | Cause | Resolution | |---|---|---| | No API key configured. Run cl_connect() first to link your dashboard account. | .compliancelintrc exists but has no saas_api_key, OR no .compliancelintrc exists. | Run cl_connect() from the project root. Sign in via the browser pop-up. The API key is auto-saved. | | not_connected: No .compliancelintrc found. (from cl_disconnect) | The repo was never paired to begin with. | No action needed — there's nothing to disconnect. | | Could not read .compliancelintrc. | The file exists but isn't valid JSON (manual edit corruption). | Open the file — fix the JSON syntax (missing comma, unquoted key, etc.). If unsure, delete the file and re-run cl_connect(). | | unauthorized / 401 from cl_sync | API key in .compliancelintrc is stale or revoked. | Run cl_connect(switch_account=true) to re-authenticate. The old key is replaced; local scan state is preserved. | | Directory not found: <path> | The project_path you passed doesn't exist on disk, or has typos. | Check the path you gave (absolute or relative-to-IDE-cwd). On Windows, use forward slashes or escape backslashes. |

Step 2

Scan / analysis failures

Errors from cl_analyze_project / cl_scan / cl_scan_all / cl_action_plan.

| Error | Cause | Resolution | |---|---|---| | Regulation 'X' is not yet supported. | You passed a regulation other than eu-ai-act. | Currently only eu-ai-act is supported. Future regulations (GDPR, NIST AI RMF) are on the roadmap. | | No project context available. Run a scan first (from cl_action_plan) | Action plan needs context loaded by a prior cl_scan / cl_scan_all. | Run cl_scan_all(project_path) first, then re-call cl_action_plan. | | cl_scan_all finishes with most articles UNABLE_TO_DETERMINE | The AI did not Grep + Read the codebase before filling compliance_answers — it filled from the 5-file skeleton in cl_analyze_project only. | This is the symptom of skipping the Deep Scan Requirement in the cl_analyze_project docstring. Re-run with the AI properly Grepping each article's scanning_strategy hints. If your AI host won't let you guide the workflow, file a host-side issue. | | cl_scan_all takes far longer than 30 seconds per article | Project size × AI provider latency exceeds the per-article timeout. | The 30-second per-article cap is hard-coded — articles that time out return UNABLE_TO_DETERMINE for that article. Consider scoping scans with cl_scan(articles="9,12,14") to bound the work. |

Step 3

Evidence and findings issues

Errors from cl_update_finding / cl_update_finding_batch / cl_verify_evidence, plus dashboard-side surfaces.

| Error / symptom | Cause | Resolution | |---|---|---| | Invalid obligation ID format: X (from cl_action_guide) | The obligation_id you passed isn't in the canonical ART<digits>-OBL-<digits> format (e.g. art13-1 won't match). | Use the format from the dashboard's per-finding card — exact case ART13-OBL-1. | | Finding stays NON_COMPLIANT after cl_update_finding action="provide_evidence" and a re-scan | The evidence you provided was rejected by the AI's verification step (didn't specifically satisfy the obligation), OR you forgot to re-run cl_scan + cl_sync after submitting evidence. | Check the finding's response history on the dashboard — the rejection rationale will be there. If the response shows the evidence was accepted, you still need cl_scan + cl_sync to update the finding's status. | | Evidence file upload via dashboard says tier_required | Evidence file upload to repo is Pro+ (see chapter 20). | Upgrade to Pro, or use evidence references (URL / text) which are also Pro+ but lighter, or git_path evidence (free-tier — point at an already-existing file in your repo via cl_update_finding evidence_type="git_path"). | | Stale evidence banner on a repo page | An evidence item's commit moved past the last scan's last_scan_commit_sha, so it may no longer represent current code state. | Re-run cl_scan to refresh the baseline; or click the banner's Sync now link. |

Step 4

Dashboard / sign-in issues

| Error / symptom | Cause | Resolution | |---|---|---| | Something went wrong page with an error_id (format err_NNNNNNNNN) | A 500 error somewhere in the request path. The error_id keys a server-side stack trace. | Click Try again first — many are transient. If it persists, click Report on GitHub and include the error_id. | | Magic-link email never arrives | (a) wrong email typed; (b) email is in spam; (c) the magic-link sender is rate-limited. | Check spam folder. If still missing after 5 minutes, request a new magic link. As a fallback, sign in with GitHub. | | 403 tier_required with required_tier: "X" | The feature you're using is gated behind a paid tier. | Either upgrade (Settings → Plans), or use the lower-tier alternative noted in the per-feature chapter. | | Dashboard repo card shows the wrong tier (e.g. you're Pro but it says Free) | Tier resolution is owner-of-repo, not signed-in user. If you were invited to a Free owner's repo, the repo carries Free's tier limits even if YOU are Pro. | This is by design (getEffectiveTierForRepo — owner pays). To unlock Pro features for that repo, the owner upgrades. | | Recently submitted evidence not visible on dashboard | The local-only cl_update_finding writes to .compliancelint/local/. Until you cl_sync, the dashboard doesn't know. | Run cl_sync(project_path) from the same project root. |

Step 5

Billing / subscription issues

| Error / symptom | Cause | Resolution | |---|---|---| | Subscription page shows subscription not active after upgrade | LemonSqueezy webhook delivery delay (rare) — the order completed on their side but our webhook hasn't processed yet. | Refresh after 30 seconds. If still incorrect after 5 minutes, contact support with the LemonSqueezy order id (visible in the success email). | | Annual upgrade price is showing the monthly amount | Cache from the page load before you toggled monthly/annual. | Hard-refresh the page (Ctrl+F5 / Cmd+Shift+R). | | Cancel subscription button is missing on a German-locale view | Variant button label issue — the cancel surface uses Kündigen / Kündigungsbutton in DE locale. | Look for Kündigen text on the same row. If genuinely missing, contact support — this is a per-locale rendering bug we want to know about. | | Lost access to features after a subscription cancellation | Cancellation takes effect at end of current billing period — features remain until then. | Verify in Settings → Plans whether the cancel is effective_at_period_end. |

Step 6

Reporting bugs cleanly

If none of the above resolves the issue, the cleanest bug report is:

1. From your IDE, run cl_report_bug — it produces a privacy-scrubbed Markdown bundle at ~/compliancelint-bugreport-{timestamp}.md (no source code, paths collapsed to ~, emails/IPs redacted)
2. Open https://github.com/ki-sum/compliancelint/issues/new
3. Attach the bundle file + describe what you were trying to do
4. If a dashboard error_id is involved, paste it in the issue body

We never auto-upload anything. The bundle is yours to review before attaching.

Related

• quick-start
• mcp-commands-reference
• concept-primer

Last updated: 2026-04-30