Troubleshooting

Most Nexgile Code problems fall into a dozen recognizable patterns with fast fixes. Start with the quick table, then read the expanded entry for your symptom. When nothing here matches, the logs section and reporting checklist at the bottom will get you unstuck.

Quick diagnosis table

Symptom	Likely cause	Fix
.nexgileignore not respected	File in the wrong location	Move it to the workspace root, not a sub-folder
Codebase search returns nothing	Index not built or Qdrant unreachable	Re-index; verify the Qdrant URL
MCP server stuck “connecting”	Wrong command path or missing env variable	Check that server’s log in the MCP settings view
Mode dropdown empty	Corrupt .nexgilemodes YAML	Validate the YAML; restore from git
Approval popups for every read	Auto-approve not enabled	Settings → Auto-Approve → enable Read
Mode-specific rules not loading	Filename doesn’t match the mode slug	.nexgilerules-<mode> must match the slug exactly
Checkpoints fail	git missing or no folder open	Install git; open a folder, not a single file
Chat panel blank	Stale UI cache	Run “Developer: Reload Window”
Errors right after install	Old cached modules	Reinstall the package and reload
Workflow chain won’t abort	Root mode isn’t Orchestrator	Whole-chain abort requires the root task to be in Orchestrator mode

Rules, ignore files, and modes

.nexgileignore seems ignored. The file only works from the workspace root — a copy inside src/ or a sub-folder does nothing. Move it to the root, then start a new task (the ignore rules are read when context is assembled). Details: .nexgileignore & Protected Files.

Mode-specific rules don’t load. The filename must match the mode’s slug character-for-character: .nexgilerules-code, not .nexgilerules-Code or .nexgilerules-coding. Find the exact slug in the mode dropdown tooltip or Using Modes. The directory form .nexgile/rules-<slug>/ has the same requirement — and note that when a rules directory exists, it takes precedence over the single-file variant.

The mode dropdown is empty or missing modes. Almost always a YAML syntax error in .nexgilemodes (or a project agent file that fails to parse). Validate the YAML — indentation and a missing customModes: top-level key are the usual culprits — or restore the file from git. The built-in modes reappear as soon as the file parses.

A GitHub specialist fails immediately. Issue Investigator, Issue Writer, Issue Fixer, PR Fixer, and Merge Resolver drive GitHub through the gh command-line tool, so a missing or unauthenticated CLI stops them at step one — usually a command-not-found or an auth error that reads like a mode fault. Run gh auth status; if it fails, install gh and run gh auth login. The error surfaces as a failed command approval, so check the command output rather than the mode. See Specialist Modes.

Search & indexing

codebase_search returns nothing (or the agent says the index is unavailable). Work through, in order: (1) indexing is enabled and the initial index finished — open the indexing popover from the status badge in the chat area and press Start Indexing if needed; (2) Qdrant is reachable at the configured URL (docker ps to confirm the container; default http://localhost:6333); (3) the embedder credentials are valid — a bad key surfaces as an indexing error; (4) the score threshold isn’t filtering everything — drop it from 0.4 toward 0.2 and retry; (5) after switching embedding model or provider, Clear Index Data and re-index — vectors from different models are not comparable. Full guide: Codebase Indexing & Semantic Search.

MCP

A server shows “connecting” forever or errors at startup. Open Settings → MCP Servers, expand the server, and read its Logs tab — stdio servers print their startup failures there. Typical causes: the command isn’t on PATH (use an absolute path), a required env variable is missing from the env block, or a first-run package download is still in progress. The built-in Playwright server deliberately starts lazily and downloads on first use — give it time or press Retry; its timeout is 240 s for exactly this reason. See Configuring MCP Servers.

Checkpoints

“Checkpoints are disabled” or restores fail. Checkpoints need git on your PATH and a real folder open (a single loose file has nowhere to shadow). One more disabler: a nested git repository inside the workspace — checkpoints turn off with an explicit error naming the nested path; move or remove the inner .git to re-enable. Remember checkpoints restore files only — terminal side effects (installs, migrations) are not undone. See Checkpoints.

Provider & API errors

Authentication errors (401/403, “invalid API key”). Re-paste the key in Settings → Providers — leading/trailing whitespace from a copy is the classic cause. Confirm the key belongs to the same account and product the provider profile expects (e.g., an OpenAI platform API key, not a ChatGPT login; the correct AWS region for Bedrock). For OpenAI-compatible endpoints, a wrong base URL produces misleading auth or 404 errors — the URL must point at the API root your server actually serves (typically ending in /v1).

Rate-limit errors (429). Two levers: set rateLimitSeconds on the API profile to enforce a minimum gap between requests, and check your quota/usage on the provider’s own dashboard — free tiers and new accounts often have tight per-minute caps. Failed requests retry automatically with exponential backoff, so a brief 429 usually resolves itself.

Context-window errors (“input too long”, “maximum context length”). Confirm auto-condensing is on (Settings → Context) and lower the trigger threshold so it condenses earlier; you can also press the condense control in the task header proactively. If the task is deep in a long session, the cleanest recovery is a fresh task seeded with the current state — e.g. “@git-changes — continue implementing X”. See Context Management.

Task flow

The task pauses saying a limit was hit. That’s allowedMaxRequests (LLM calls per task) or allowedMaxCost (USD per task) doing its job: the task pauses with a “Reset and Continue” prompt; approving resets the meter and resumes. Before continuing, skim what the agent has been doing — a tripped cap on a task you expected to be small is diagnostic information, often a loop. See Command Guardrails & Limits.

Commands time out (or hang forever). commandExecutionTimeout defaults to 0 (no timeout) — if you set one and a legitimate long build trips it, either raise it (max 600 s) or add that command’s prefix to commandTimeoutAllowlist to exempt it. For processes meant to run indefinitely (dev servers, watchers), the agent should pass the timeout parameter on execute_command so it can collect early output and move on; suggest that in your reply if it’s waiting forever on npm run dev.

Approval fatigue. If you’re clicking Approve for every file read, enable Auto-Approve → Read and keep writes/commands manual — the standard first step in Auto-Approving Actions.

The Workflow Mode chain won’t stop. The Stop button aborts the entire delegation chain only when the root task is in Orchestrator mode (which is how Workflow Mode always starts). If you manually built a chain from a different root, stop the child tasks individually. See Workflow Mode.

Where to find logs

• Output channel: View → Output, then pick Nexgile-Code from the dropdown. Extension activation, API, and service errors land here — this is the first thing to check for anything that fails silently.
• MCP server logs: per-server Logs tab in Settings → MCP Servers.
• Developer console: Help → Toggle Developer Tools for webview (panel UI) errors — useful for a blank chat panel.
• Debug mode: Settings → About → “Enable debug mode” adds task-header buttons that dump the API conversation history and UI messages as prettified JSON — ideal for support bundles.

Reporting an issue

Write to support@nexgile.com. Include:

1. Nx IDE / Nexgile Code version (Settings → About).
2. Provider and model in use (e.g., Anthropic / your configured Claude model), and whether the failure reproduces with a second provider.
3. What you did, what you expected, what happened — with the exact error text.
4. Relevant lines from the Nexgile-Code output channel, and the MCP server log if MCP-related.
5. Whether it reproduces after “Developer: Reload Window” and in a minimal new workspace.

Caution

never include API keys, tokens, or proprietary code you can’t share in a support mail. Redact key values — the error messages and logs are what matter.

Related

• FAQ
• Human-in-the-Loop Playbook — recovery procedures
• Settings Reference