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.

A
Written By Atakan KayaLast updated 3 months ago

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.

  1. Refresh tools/list in the IDE.
  2. If the payload names a suggested_mode, call switch_to_mode(target_mode='<suggested_mode>').
  3. 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.