LatentCodeReference

Troubleshooting

Find out what went wrong, fix the common problems, and reset LatentCode if you need to.

First steps

Command	Tells you
latentcode config	Which gateway you're connected to, whether an API key is set, the default model and how many models were imported.
latentcode models	Whether the gateway accepts your key right now, and your tier.
latentcode debug config	The configuration LatentCode actually uses, after merging every file.
latentcode debug info	Version, operating system, terminal and loaded plugins. Include it when you report a problem.
latentcode debug paths	Where config, data, logs and cache are on this machine.

Logs

Each run writes a log file to ~/.local/share/latentcode/log/, named by the time it started, for example 2026-09-28T093951.log. The 10 most recent are kept. When an unexpected error stops LatentCode, it prints the path of the log file to check.

$latentcode --print-logs --log-level DEBUG run "hello"

--print-logs also writes the log to stderr, and --log-level DEBUG adds detail. Both work with every command.

Connection problems

"Invalid API key"

The gateway rejected the key. It may have been regenerated, which invalidates the old one. Copy the current key from your Account page and save it again:

$latentcode config set api-key ls-your-key

"Could not reach gateway (… → HTTP 404)" or "Could not reach …"

The gateway URL is wrong or unreachable. It should be your LatentStack address followed by /v1. Check it with latentcode config get base-url and fix it with:

$latentcode config set base-url https://your-host/v1

If the URL is right, check your network, VPN or proxy.

"No models returned for this key (empty tier?)"

Your key works but your tier allows no models. Ask your administrator to assign models to your tier, then run latentcode config models --refresh.

The Connect LatentRouter dialog keeps coming back

The TUI needs both a gateway URL and an API key, and asks until both are saved. Enter them, or quit with ctrl+c and run latentcode config set base-url … and latentcode config set api-key ….

A model I expect isn't in the list, or requests fail with a permissions error

Models depend on your organization and tier. Check which organization is active with /org; run latentcode models to see what the gateway allows right now.

Startup and configuration

LatentCode stops at startup with a config error

A config file has invalid JSON or a value of the wrong type. The message names the file, and for JSON syntax errors the line and column. Fix it, or move the file aside to check. Unknown keys don't cause errors; they're ignored, so a misspelled setting silently does nothing. Compare with latentcode debug config.

My setting has no effect

Another file may override it: project config beats global config, and settings your administrator enforces beat both. latentcode debug config shows the final values. theme and keybinds belong in tui.json, not latentcode.json. See Configuration.

A plugin breaks LatentCode

Start with latentcode --pure to skip external plugins. If that works, remove plugins from the plugin list or the plugins/ folders one at a time.

While working

"Shell command could not start because OS sandbox preparation failed"

Shell commands run in an operating-system sandbox. On Linux that needs bubblewrap: install the bubblewrap package so /usr/bin/bwrap exists. To run without the sandbox, set LATENTCODE_OS_SANDBOX=false.

latentcode run prints "permission requested: … auto-rejecting"

Nobody can approve requests in run, so they're rejected. Allow what the job needs in your permission config or LATENTCODE_PERMISSION, or use --auto in a disposable environment.

The agent keeps asking about the same kind of command

Choose Yes, don't ask again this session, or add an allow rule to your config to make it permanent.

/undo removed my message but didn't restore the files

File snapshots only work in git repositories, and only when snapshot isn't set to false. Untracked files over 2 MB aren't snapshotted. Run git init in projects you want to undo in.

The conversation never compacts and hits the context limit

Check that compaction.auto isn't false and LATENTCODE_DISABLE_AUTOCOMPACT isn't set. Compaction also needs the model's context window from your gateway; if the sidebar shows no limit, ask your administrator to set it. Run /compact to compact by hand.

shift+return sends the message instead of adding a line

Many terminals send the same key for both. Use ctrl+j, which works everywhere, or alt+return. See Keybindings.

I can't select text with the mouse

LatentCode captures the mouse for scrolling and clicking. Set "mouse": false in tui.json (or LATENTCODE_DISABLE_MOUSE=1) to give it back to your terminal.

"Session not found"

The ID passed to -s doesn't exist in this machine's database. latentcode session list shows the IDs you have.

For MCP connection and login problems, see MCP servers.

Update

LatentCode checks for updates on start. When one has been installed it restarts once your sessions are idle, or tells you it will be used next time. To update by hand:

$latentcode upgrade

Turn automatic updates off with "autoupdate": false in your global config, or get a notice without installing with "autoupdate": "notify".

Reset

Reconnect

To start the connection over while keeping your sessions and settings:

Bash

latentcode config clear all
latentcode config set base-url https://your-host/v1
latentcode config set api-key ls-your-key

Start from scratch

These folders hold everything LatentCode keeps. Quit LatentCode and back them up before deleting anything:

Folder	Contains	Deleting it
~/.config/latentcode	Global config, API key, agents, commands, skills	Resets your settings and disconnects you.
~/.local/share/latentcode	Sessions database, memory, snapshots, logs, MCP logins	Deletes all sessions and memory.
~/.local/state/latentcode	Recent and favorite models, selected organization	Resets those choices.
~/.cache/latentcode	Cached downloads, such as the model catalog	Safe; it's rebuilt.

latentcode uninstall removes all of these and the program itself. Add --keep-config or --keep-data to keep settings or sessions, and --dry-run to see what would go.

There's no way to recover deleted sessions. Back up the file shown by latentcode db path first if you might want them back.