Skip to Content
Latch Docs

Troubleshooting

Inspect the checks Latch found and diagnose missing output.

Start with latch status from the project directory, or ask the agent for latch_status in a plugin session. It shows the resolved checks and recent hook activity. Use latch explain turn_end to inspect one event in more detail. CLI reference

What you seeStart here
Install or startup failsRelease download or agent startup
An edit or turn produces no outputThe hook is quiet
Latch reports that a command couldn’t startA command failed to launch
Your agent can’t call a Latch toolTool availability
Your check fails but the agent doesn’t see itTurn-end delivery

The release download returns 404

Open GitHub Releases and select the archive for your machine. The project and its release assets are public.

The agent cannot sign in or start a turn

Use codex login, claude auth login, or copilot login for your CLI, then start a new session. In OpenCode, connect a model provider and select a working model before running your first check.

The hook is quiet

  1. Run latch explain for the event from the project directory. Check configured, the command list, and any file filters. If config is null and configured is true, Latch found a package script.
  2. Run the same event with latch run. Successful commands are silent by default. Append && echo passed in a POSIX shell to confirm success.
  3. Confirm your harness loaded the plugin. If you installed the CLI separately, check that latch --version works from the terminal you use to start it. In Codex, approve project trust first, then check that you trusted the hooks in /hooks.
  4. Make a Git-visible change using a supported native edit tool. The default after_edit gate skips no-op edits. File filters can also skip a check.

A command failed to launch

Check the executable in the command shown by latch explain. Install that runner or tool, then start your harness from a terminal that can find it.

The agent cannot find the Latch tool

Start a new harness session with the plugin installed. If you installed the CLI separately, verify that the session can launch latch. The plugin exposes run_turn_end through a local MCP server.

A turn-end failure is missing from the chat

Check where your harness shows turn-end feedback. Some integrations pass the report to the model on your next prompt in the same session and project. With continue_once enabled on a supported agent, it receives the failure automatically. Run latch explain turn_end from the project directory to confirm the setting.

On this page