LEX AI Operations and Troubleshooting

What each mode does to your repository, the mandatory halt-on-error procedure, stale-tool recovery, the secrets rule, and what support can diagnose.

A
Written By Atakan KayaLast updated 3 months ago

LEX AI Operations and Troubleshooting

This page covers what LEX AI does to your repository, what to do when a tool call fails, and what support can see afterwards.

Git and GitHub behavior by mode

Mode

Git behaviour

forward, mvp_completion

Own remote delivery: a run branch, a commit and push after every step, a pull request, and a squash-merge at the end.

mvp_generator

Local commits only — no remote and no push. LEX_MVP_NO_GIT=1 disables even those.

brief

None. It writes the contract into your working tree.

edit

A branch per run, one commit per task, then push and a pull request. It never merges.

backward, review, test, input

No remote writes. They may clone a repository in order to read it, and leave their output in your working tree for you to commit.

deploy

None, deliberately. A deployment run writes configuration, and an auto-commit is how a populated .env reaches a remote.

Mandatory error handling

When an MCP tool returns ok: false:

  1. Stop workflow actions immediately — no further tool calls, no git, no shell commands.
  2. Present the troubleshooting payload to the user.
  3. Wait for the user to resolve it.
  4. Retry the same tool call.

The rule is absolute because the failures that halt are the ones only a person can clear: a missing credential, an unreachable remote, a tool surface that no longer matches. Work produced after ignoring one has to be thrown away, and every payload carries an ok key so there is always a field to check.

Stale-tool recovery

A stale-tool payload means the IDE cached a tool list from a previous mode. It carries active_mode, suggested_mode, and tool_surface_epoch.

  • Refresh the IDE tool list.
  • Switch mode when one is suggested.
  • Retry the original call.

Switching mode is the fix here. It is also the fix for test mode's user-story prerequisite gate, which halts until the project is handed to backward mode and returned to test afterwards. Never switch mode to route around any other error.

Secrets

Deploy mode carries an explicit, non-waivable rule against recording a secret value in an artifact: only key names and where they belong are written, an agent may not type a credential into a file on the user's behalf, and a credential found already committed halts the run rather than being reported as a finding. No comparable rule is enforced in the other modes, so review their output before committing it. lex ai-issue-report masks credential values before writing the bundle.

Observable problem areas

Support can usually diagnose:

  • setup, environment-registration and credential issues
  • workflow step and run-state problems
  • user-change re-execution triggers
  • mode and tool-surface mismatches
  • reverse documentation coverage gaps
  • remote call and network timing failures

See Troubleshooting, Git and GitHub, and What we can diagnose.

Was this helpful?

Your feedback shapes what we write next.