Troubleshooting
Symptom-by-symptom fixes for stale tool lists, wrong project or mode, git failures, refused interview answers, blocked test runs, rejected completions, unreachable deployment steps, and MVP caps.
Troubleshooting
Most problems fall into a few well-understood buckets. The golden rule throughout: when a tool returns ok: false, stop, read the troubleshooting block, fix the underlying issue, and retry the same tool — never improvise a workaround and never run git to patch infrastructure the server owns.
"A tool is missing" or "stale tool" errors
Symptom: the assistant reports a tool is not available, or you see stale_tool_call: true. Cause: the IDE cached the previous mode's tool list after a switch. The server intercepts the call and returns a structured payload naming the active_mode, a suggested_mode and the current tool_surface_epoch, rather than a raw method-not-found error.
- Refresh
tools/listin the IDE. - If the payload names a
suggested_mode, callswitch_to_mode(target_mode='<suggested_mode>'). - Retry the original tool call.
Never work around it by calling a different tool. See Mode switching.
Wrong project or wrong mode
Symptom: the assistant acts on the wrong folder, or offers tools you did not expect. Fix: open lex ai-dashboard, confirm the project root shown in System Information (set LEX_MCP_PROJECT_DIR, pass -p, or run from the right folder), confirm the active mode, then start a fresh assistant request. LEX_MCP_MODE is only a mirror the server rewrites on start — change mode through the dashboard or a switch tool, not by editing the variable.
Git or GitHub failures (Forward, MVP Completion)
Symptom: notify_step_complete or finalize_workflow returns ok: false with a git troubleshooting block. Cause: usually credentials or remote state. Fix: make sure GITHUB_TOKEN (or COPILOT_GITHUB_TOKEN) with repo scope is set in the environment or the project .env, resolve the described issue, then retry the same tool. The server already auto-repairs lock files, non-fast-forward pushes and missing upstreams; it only surfaces ok: false once repair is exhausted. See Git and GitHub.
The interview will not accept an answer
Symptom: Brief refuses your answer or refuses skip_topic. Cause: the answer matched a filler phrase such as "standard" or "you decide", fell short of an essential field's minimum length, or the topic still holds a field that gates completion. Fix: answer the sharper follow-up the refusal supplies. If you genuinely do not know, say so — that is recorded as an open decision — or call finish_interview_now, which ends the interview at your word and records every unanswered field as a named gap. See Brief.
A test run will not open
Symptom: kickstart_test_run returns prerequisite_blocked. Cause: there is no user-story document to test against, and this gate cannot be waived — an assertion derived from the implementation pins current behaviour, bugs included, and can never fail. Fix: run dispatch_reverse_prerequisite, let Backward produce the documentation, and the test session resumes on the way back. See Test.
A change is reported complete but rejected
Symptom: notify_change_complete (Input) returns ok: false. Cause: an artifact the completion declares is not on disk. Fix: write the file, or correct the declared path, then report completion again. See Input.
A deployment step cannot be fetched
Symptom: get_deployment_step halts. Cause: the remote Lex deployment handbook is unreachable or unauthenticated; deploy step bodies are never synthesised locally, because a plausible-sounding instruction aimed at a production system is worse than no instruction. Fix: check the connectivity and credential settings the payload names, then retry the same step. See Deploy.
MVP scope rejected, or MVP will not finalize
Scope rejection means a hard cap: 10 requirements of 240 characters each, 5 entities, 8 fields per entity. Trim the scope and plan the rest for MVP Completion. A refused finalize_mvp means run_boot_checklist() has a failing critical check — apply the verifier's fix plan and re-run the checklist until it passes.
Environment looks unhealthy
Run lex ai-verify. It restores generated files that are missing or have drifted from what the installed packages ship, and prunes assets left over from a previous mode, which would otherwise leave the assistant reading a mixed tool surface. If you are on an old build, run lex ai-update, then lex setup-with-ai to refresh the payload, then verify again. The command is hyphenated; lex setup_with_ai does not exist.
When you are stuck
lex ai-issue-report builds a diagnostic bundle under .lex-ai-reports/. Credential values are masked on the way in, and manifest.json records which files were touched and how many values were replaced in each, so support can tell a masked credential from a missing one. See What we can diagnose.
Was this helpful?
Your feedback shapes what we write next.
