Troubleshooting
AI Coding Troubleshooting
Start with the observable failure, isolate the affected layer, and verify the fix before reinstalling tools or rewriting project instructions.
Reliable troubleshooting separates installation, authentication, repository discovery, context, permissions, execution, and deployment instead of treating every failure as a model problem.
What should you check first when a coding agent fails?
Identify the failing layer before changing the whole setup. Installation, authentication, repository instructions, model allowances and project commands produce different symptoms. Capture the exact message without credentials, check the matching official documentation and try one reversible fix. Verify the original task again so a disappearing error does not hide another failure.
Installation and authentication
Separate missing executables, stale credentials, browser callbacks, and environment mismatches before reinstalling.
Indexing and tool connections
Diagnose stalled repository context and MCP failures from observable client state and server evidence.
Check workspace scope, progress, exclusions, network diagnostics, and extensions.
Practical guideMCP Server Connection FailedCheck config scope, transport, environment, approval, logs, and tool discovery.
Practical guideCursor Not Indexing Your Codebase: Diagnose It FastA symptom-to-fix guide for missing files, weak repository answers, stale context, ignored folders, and oversized workspaces.
Repository instructions not working
Check actual loaded context, directory scope, activation metadata, conflicts, and verifiable rule wording.
Fix new-session discovery, root scope, overrides, precedence, and size limits.
Practical guideCLAUDE.md Not WorkingFix supported locations, on-demand loading, imports, and conflicts.
Practical guideCursor Rules Not WorkingFix .mdc recognition, activation modes, globs, and product-surface expectations.
Agent output and production
Catch excessive changes, missing evidence, unsafe assumptions, and deployed behavior that differs from the task.
Review AI-written code by behavior and risk, including dependencies, auth, data, tests, accessibility, performance, and rollback.
Practical guideAI Coding Agent Workflow: From Task to Reviewed MergeA practical agent-first workflow covering task briefs, context, worktrees, permissions, tests, handoff, and human review.
Practical guideVibe Coding Production ChecklistA launch gate for AI-built apps covering accounts, data access, secrets, payments, errors, monitoring, SEO, and rollback.
Login expiry and usage limits
Separate expired authentication, shared allowances and metered spending.
Continue by task