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 see | Start here |
|---|---|
| Install or startup fails | Release download or agent startup |
| An edit or turn produces no output | The hook is quiet |
| Latch reports that a command couldn’t start | A command failed to launch |
| Your agent can’t call a Latch tool | Tool availability |
| Your check fails but the agent doesn’t see it | Turn-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
- Run
latch explainfor the event from the project directory. Checkconfigured, the command list, and any file filters. Ifconfigisnullandconfiguredistrue, Latch found a package script. - Run the same event with
latch run. Successful commands are silent by default. Append&& echo passedin a POSIX shell to confirm success. - Confirm your harness loaded the plugin. If you installed the CLI separately,
check that
latch --versionworks from the terminal you use to start it. In Codex, approve project trust first, then check that you trusted the hooks in/hooks. - Make a Git-visible change using a supported native edit tool. The default
after_editgate 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.