--- title: Troubleshooting description: Find your symptom and its fix, run the doctor check, and collect what to send when you need help. canonical_url: https://lookout.itoowasinarcadia.com/docs/troubleshooting type: help section: Help last_updated: 2026-10-22 related: - https://lookout.itoowasinarcadia.com/docs/errors - https://lookout.itoowasinarcadia.com/docs/files - https://lookout.itoowasinarcadia.com/docs/machines --- > Every page of these docs: https://lookout.itoowasinarcadia.com/llms.txt # Troubleshooting Find your symptom and its fix, run the doctor check, and collect what to send when you need help. Find what you see in the table. If nothing matches, run the doctor. If you still need help, [send a report](https://lookout.itoowasinarcadia.com/docs/troubleshooting#report). ## Find your symptom | Symptom | Go to | |---|---| | A turn ends with an error notice, or a line such as **Failed** | [Error reference](https://lookout.itoowasinarcadia.com/docs/errors#find) | | A turn reads **Interrupted** or **Paused** | [How a turn ends](https://lookout.itoowasinarcadia.com/docs/errors#turn-endings) | | The message box says the model isn't available | [When a model can't run](https://lookout.itoowasinarcadia.com/docs/models#cant-run) | | **Plan limit reached** | [When a plan runs out](https://lookout.itoowasinarcadia.com/docs/usage#plan-runs-out) | | **Context full**, or a long chat keeps summarizing | [When the context runs out](https://lookout.itoowasinarcadia.com/docs/context#full) | | The agent says a command is not found | [The agent can't find a command](https://lookout.itoowasinarcadia.com/docs/troubleshooting#path) | | The agent changed files you wanted to keep | [Restore files to before a turn](https://lookout.itoowasinarcadia.com/docs/checkpoints#restore) | | The agent reads files it should leave alone | [Keep the agent out of files](https://lookout.itoowasinarcadia.com/docs/rules#ignore) | | Commits or pushes fail on a server | [Set up git and tools on a server](https://lookout.itoowasinarcadia.com/docs/machines#git) | | Another machine doesn't answer | [Check a machine's status](https://lookout.itoowasinarcadia.com/docs/machines#presence) | | The browser says it can't reach Lookout, but the server runs | [The browser isn't signed in](https://lookout.itoowasinarcadia.com/docs/troubleshooting#browser-link) | | macOS says Lookout is damaged and can't be opened | [macOS says Lookout is damaged](https://lookout.itoowasinarcadia.com/docs/troubleshooting#damaged) | | Dictation shows **Microphone access is off** or another error | [Dictation failed](https://lookout.itoowasinarcadia.com/docs/errors#dictation-failed) | | The Mac app shows **Lookout could not start** | [Lookout could not start](https://lookout.itoowasinarcadia.com/docs/errors#could-not-start) | | **The update didn't install** | [The update didn't install](https://lookout.itoowasinarcadia.com/docs/errors#update-didnt-install) | | `lookout` ends with an error | [In the terminal](https://lookout.itoowasinarcadia.com/docs/errors#terminal) | | None of these | [Run the doctor](https://lookout.itoowasinarcadia.com/docs/troubleshooting#doctor) | | You need help, or have feedback | [Collect a report](https://lookout.itoowasinarcadia.com/docs/troubleshooting#report) | ## Run the doctor `lookout doctor` checks what chats on a machine need: a signed-in provider, git and its identity, access to each project's remote, the commands projects require, the shell environment, capacity, disk and the sign-in to your account. ```sh lookout doctor ``` The first line says `ready`, or how many problems it found. A line per check follows, then each problem on a line starting with `!`, with its fix: ```text vps-1: 1 problem Git 2.43.0; identity none; credentials github.com ! git has no identity, so commits fail: lookout git setup --name NAME --email EMAIL. ``` It exits with `1` when it finds a problem. `--on vps-1` checks another machine, and `--json` prints the report as JSON. The JSON report ends with `recent`: the last 24 hours on that machine, grouped by the Lookout version that ran them. It counts how turns ended, errors by code, provider and account id, failed background passes and Task runs, declined requests and the ones another model answered, and how often the server stalled. Its `hangs` list the last five times the server stopped answering for 10 seconds or more: what it was in, how long it lasted, and whether it came back or was restarted. Its chats with the most unfinished turns list each kind's last two with what came after: the next turn's cause, how long it took and onto which model, or how long the chat has waited. Its `rounds` split each model's request time by phase: queued, waiting for headers, prefill, thinking, writing, failed tries and the waits between them. It names accounts and chats by id only. The doctor comes with the `lookout` command: to check a Mac that has only the app, run `lookout doctor --on` with the Mac's name from another machine of your account. After the problems, lines starting with `-` are notices, which don't count as problems: the chats active in the last 24 hours whose memory index is over about 8,000 tokens, or whose deferred tool listing (the large connectors' tools, kept out of the tool list) is over 2 KB, each with its size. Both go with every request those chats send. ### A Mac that slows down with plenty of memory in use The doctor's `Host` line shows the swap in use, Lookout's own memory, the processes holding the most memory outside it (every user's, macOS's own services included) and the scratch root. A macOS service that should hold a few megabytes sometimes grows without end until it is restarted: fseventsd, which tracks file changes, once held 13 GB of a 16 GB Mac. When fseventsd, Spotlight's mds or mds_stores, or mdworker_shared holds more than 1 GB, the doctor lists it as a problem with the one command that restarts it, such as: ```text ! fseventsd (pid 1830, root) holds 13.0 GB, a runaway that grows until it is restarted. Restart it: sudo kill -9 1830 (launchd starts it again at once; apps that watch files may need a restart to watch again). ``` Run that command yourself in Terminal: it asks for your password, and Lookout never runs it for you. `sudo killall fseventsd` is not enough. macOS starts the service again at once, so no restart of the Mac is needed. Another of macOS's services past 1 GB shows as a notice with no command. ### What a chat sends with every request `lookout doctor --head CHAT` shows a chat's newest head part by part: what goes to the model before the conversation, every request. CHAT is the chat's id or its first characters. ```text 3f2a91c0-5d7e-4b8a-9c11-0e6f2d4b7a85 (claude-opus-5-5): head 97,434 bytes, 24,367 tokens (estimated, bytes / 4), as of 2026-10-21T12:41:58.066Z bytes tokens share system prompt 5,001 1,251 5% rules 21,834 5,459 22% user 484 121 0% project 21,346 5,337 22% tools 28,293 7,080 29% environment 42,306 10,577 43% skills 2,758 690 3% memory 38,344 9,586 39% ``` Rules are your own rules and the project's. Tools split into Lookout's, each connector's and the deferred listing. The environment splits into the user info, the skills list, each memory index and the rest. Bytes are exact; tokens are estimated as bytes / 4, so a model's own count differs by a tenth or so. `--json` prints the same parts, and `--on` reads a chat on another machine. | Problem | Fix | |---|---| | No model provider is signed in | [Connect a provider](https://lookout.itoowasinarcadia.com/docs/models#connect) on this machine or another device of your account. | | git is not installed | Install git. Checkpoints, worktrees and clones need it. | | git has no identity, so commits fail | `lookout git setup --name "Your Name" --email you@example.com` | | PROJECT: cannot reach REPO | When the code in parentheses is `git_auth`, pipe in a token for the forge: `printf %s "$TOKEN" \| lookout git setup --host github.com --token-stdin`. Otherwise check the remote. | | PROVIDER is held back here | This machine's sign-in for the provider differs from your account's, and Lookout won't pick one alone. `lookout providers use-account PROVIDER` takes your account's; `lookout providers keep PROVIDER` puts this machine's in your account. The line names every choice. | | PROJECT requires COMMAND | Install the command for your user and restart Lookout, or add its folder to `path` in the project's [worktree file](https://lookout.itoowasinarcadia.com/docs/worktrees#file). | | PROJECT: an error in its worktree file | Fix `.lookout/worktree.json` as the line says. Until then, chats there start without its `path` and `env`, and worktree chats don't start. | | PROJECT: .lookout/worktree.json is not approved on this machine | Read the file's commands in **Project settings** and choose **Approve** ([Approve a worktree file](https://lookout.itoowasinarcadia.com/docs/worktrees#approve)). Until then its setup, teardown, `path` and `env` don't run there. | | The login shell gave no environment | Fix your shell's startup files, or list folders in `path` in the project's worktree file. | | Only N GB free where Lookout keeps its data | Free disk space: clones and worktrees need room. | | New delegated turns wait | Chats that connected apps start wait for room: see [Limit what a machine takes](https://lookout.itoowasinarcadia.com/docs/machines#capacity). | | systemd lingering is off | `sudo loginctl enable-linger $USER`, so the service keeps running after you log out. | | Not signed in to a Lookout account | `lookout login`, or on a Mac with the app, sign in there | | The server hung and its watchdog killed it | Lookout stopped answering for two minutes and restarted itself. The `Hangs` line names what it was in. If it happens again, [send a report](https://lookout.itoowasinarcadia.com/docs/troubleshooting#report) with the newest file in `~/.lookout/hangs/`. | `lookout status` says whether this machine is signed in and how your other devices see it. ## The agent can't find a command The agent's commands run with the environment your login shell sets up, which Lookout reads once, when it starts. After you install a tool: 1. Restart Lookout: quit the Mac app and open it again. On a server, restart the service as [Set up git and tools on a server](https://lookout.itoowasinarcadia.com/docs/machines#git) shows. 2. Run `lookout doctor`. Its `Shell env` line names your login shell and the folders it added to `PATH`. If the doctor says the login shell gave no environment, your shell's startup files failed: fix them, then restart Lookout. ## The browser isn't signed in You opened Lookout in a browser and the page says **This browser isn't signed in to this Lookout**, while the server is running. The page on its own holds nothing: a browser gets in with a one time link, and this browser has not opened one yet, or its sign in is gone. On the machine running Lookout, run: ```sh lookout link ``` Open the link it prints in this browser. The link works once, for 10 minutes. The Mac app never needs it: its window is signed in already. ## macOS says Lookout is damaged You open the Mac app and macOS says Lookout is damaged and can't be opened. Lookout is not damaged: the app is not notarized yet, so macOS refuses apps it downloaded until you say this one is fine. Run this once in Terminal, then open Lookout again: ```sh xattr -cr /Applications/Lookout.app ``` ## Find the logs In the Mac app, choose **Help › Show Logs in Finder**. On a Linux server, run `journalctl --user -u lookout -f` as the user Lookout runs as. [Files and folders](https://lookout.itoowasinarcadia.com/docs/files#logs) lists every log. Each line of the Mac app's `server.log` starts with the time it was written, and each start of the server adds a line naming its version. Past 20 MB the log moves to `server.log.1` when the server next starts, so the two files hold the recent history. ## Collect a report When you ask for help, say what you did, what you expected and what happened, and send these three: 1. The chat: right-click it in the sidebar and choose **Export**. Lookout saves it as a `.zip`. 2. The logs: in the Mac app, **Help › Show Logs in Finder**, then `server.log`, `update.log` and `renderer.jsonl`. On a server, the service's log (see [Find the logs](https://lookout.itoowasinarcadia.com/docs/troubleshooting#logs)). 3. The doctor's report: `lookout doctor --json > doctor.json` on the machine the chat ran on, or with `--on` and that machine's name from another one. > [!WARNING] > An export holds what the chat saw: file contents, command output, and the diffs of files such as `.env`. Read it > before you share it. [What an export holds](https://lookout.itoowasinarcadia.com/docs/files#export) lists its parts. Email the report to: [feedback@itoowasinarcadia.com](mailto:feedback@itoowasinarcadia.com) The same address takes questions and feedback. In the Mac app, **Help › Send Feedback** starts the mail with the app's version in the subject; `lookout --help` ends with the address. ## Related - [Error reference](https://lookout.itoowasinarcadia.com/docs/errors.md): The messages Lookout shows when something fails, what each one means and what to do. - [Files and folders](https://lookout.itoowasinarcadia.com/docs/files.md): What Lookout keeps on disk, which files in a project it reads, and what an export holds. - [Machines](https://lookout.itoowasinarcadia.com/docs/machines.md): Run chats on your other Macs and on your servers, from the app or the terminal.