Troubleshooting

Common problems and how to fix them. Pick a category below - each entry follows the same shape: a short description of what you’re seeing, then what to do about it.

If your problem isn’t here, the app version and a description of the steps that reproduce it are usually enough to file a useful bug report at github.com/ztcs-software/loach/issues.

Categories

• Providers & connectionsOllama not running or failing to start, OpenAI 401s and keys withheld over plain http://, OpenAI 400s, keys that won’t save on Linux or Windows, empty model lists, API models missing from the picker.
• Sending & receiving messagesStuck “waiting” chats, half-streamed replies, missing thinking traces, formulas shown as raw TeX, metrics that are missing or don’t match your provider, Compact context greyed out, off-topic answers, HTML previews that don’t run, messages starting with /.
• Performance & VRAMOut-of-memory errors, onboarding sizing your machine wrong, sluggish UI, slow first reply after launch, making Ollama generate faster.
• AttachmentsThe 20 MB file limit, files Loach can’t read, empty scanned PDFs, legacy .doc files, garbled text files, truncated documents, PDFs without a preview, refused drops, images on models without vision or sent with too little detail, pastes from Office.
• Tools, MCP & foldersIgnored URLs, blocked internal hosts, failed fetches and proxies, MCP handshake errors and redirects, local (stdio) servers that won’t start or arrive disabled after an import, replies waiting for a tool approval, the 10-tool-turn limit, models that don’t support tools, no tools in Private Chat, and working folders, file names and edits that get refused.
• Spaces & memorySpace or global memories that aren’t being saved, undoing or editing a wrong fact, “Memory is off” from /remember, facts marked “not sent”, Space uploads that are refused or ignored, Space instructions replacing your custom ones.
• LibraryEmbedding paused or indexing that never finishes, links that won’t add, sources the model ignores, Chinese, Japanese or Thai keyword search, Truncated items, unreadable uploads, finding an item.
• App lockForgotten PINs, rate-limited unlocks, re-authentication prompts after unlock, Loach locking itself mid-session or later than the timeout, macOS keychain prompts, or opening without asking for your PIN.
• Models editorSave as new model validation errors and replace prompts, stuck pulls, delete failures, a per-model Thinking preference that doesn’t apply.
• UpdatesMissing install buttons on Linux, password prompts on .deb / .rpm updates, “latest version” while GitHub shows something newer, no update notice at launch or after Later, downloads you can’t cancel, signature failures.
• Data, import & exportRejected JSON imports (a 1.6 backup in an older Loach included), what’s missing after a restore, what “Remove my data” keeps that “Factory reset” clears, a database that stays large after deleting chats.
• Appearance & windowAurora tearing on integrated GPUs, partial font-size scaling, missing animations, the sidebar collapsing on its own.
• Search paletteCtrl+K or Ctrl+F doing nothing (onboarding, the lock screen, Private Chat and open dialogs block the palette), phrases and Library items search can’t find.
• PlatformmacOS “damaged” warning on first launch, Intel Macs and older Safari, closing the window and Ctrl shortcuts on macOS, older Linux distributions, Credential Manager writes blocked on managed Windows machines, “Loach failed to start”, a second launch.