> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylinger.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Find and fix common problems with the linger command, a Linger server, a Computer, and its Runtimes. Most problems sit in one of two places: the server, or a Computer, a machine connected to Linger. Each place has its own check command. Find your problem in the table, run the first check, then read its section. | Problem | What to try first | | - | - | | The app does not open | Desktop app: **Save Diagnostics…** in the tray menu. Docker Compose: `docker compose ps`, then `docker compose logs `. | | The Computer shows offline, or agents never answer | On that Computer, run `linger-computer daemon status` and `linger-computer doctor`. | | "No runtime is ready yet" | Run `linger-computer runtime check`. | | A desktop action returns a `COMPUTER_` error | Find the code in the desktop errors table. | | Other computers cannot connect | Set the four network variables and run Docker Compose again. | | The microphone is blocked | Put an HTTPS proxy in front of port 3000. | | Saving a Composio key or connecting an app fails | See the Composio errors in [Connected apps](https://docs.heylinger.com/computer/connected-apps.md#turn-on-connected-apps-for-your-server). | | `pnpm dev` cannot reach the database | Start PostgreSQL first: `docker compose up --detach --wait postgres`. | ## The app does not open Find out which service is down, then read its logs. The commands depend on how you installed Linger. For the desktop app, open the tray menu and choose **Show Logs**, or **Save Diagnostics…** to collect the logs of every service in one file. For Docker Compose, list the services and read the logs of the one that failed. Replace `teamhub` with the service name that `docker compose ps` shows: ```bash theme={null} docker compose ps docker compose logs teamhub ``` If you changed `WEB_PUBLIC_ORIGIN` to an address other than `localhost`, check `LINGER_SECRET_SEED`. The server refuses to start with the public development seed on a non-loopback address. [Serve other computers on your network](https://docs.heylinger.com/admin/network.md) shows how to replace it. ## The Computer shows offline, or agents never answer The Computer Daemon, the background process that connects the Computer to Linger, is stopped or cannot reach the server. Run these commands on that Computer, in order: **1. Check the Daemon** ```bash theme={null} linger-computer daemon status ``` The output shows the process, the server connection, and a summary of the Runtimes. **2. Run the diagnostics** ```bash theme={null} linger-computer doctor ``` **3. Read the logs** ```bash theme={null} linger-computer daemon logs ``` The command shows the last 200 lines. Add `-f` to keep printing new lines. **4. Restart the Daemon** ```bash theme={null} linger-computer daemon restart ``` If the Computer was never signed in, run `linger-computer login`. It saves the credential and starts the Daemon. If it signs in to the wrong server, pass the right address with `--web-url`. `linger-computer auth status` shows the server this Computer is authorized for. ## "No runtime is ready yet" No Runtime on the Computer is installed and signed in. Linger needs Claude Code, Codex, or Pi. This command lists what to install or sign in to: ```bash theme={null} linger-computer runtime check ``` The check needs no sign-in and no running Daemon. It gives each Runtime one status: | Status | Meaning | | - | - | | `READY` | Install, version, sign-in, and protocol checks passed. | | `NOT_INSTALLED` | No usable executable was found. | | `AUTH_REQUIRED` | The Runtime needs sign-in or credentials. | | `INCOMPATIBLE` | The version or protocol is not supported. | | `ERROR` | The check failed, and the output shows the reason. | A plain check does not ask the model for a reply. To wait for a real reply, add `--live`: ```bash theme={null} linger-computer runtime check codex --live ``` The `--live` check uses your model quota. ## Read a `linger-computer` exit code Every `linger-computer` command exits with a code that names the kind of failure. Scripts can branch on it. | Code | Meaning | What to do | | - | - | - | | `0` | The command succeeded. | Nothing. | | `1` | An internal error occurred. | Read the message and the Daemon logs. | | `2` | The command or its options are wrong, or plain `linger-computer` found several environments. | Check `--help`, or run the environment's own command, such as `linger-computer-local-3000`. | | `10` | The configuration is missing, unreadable, or not permitted. | Check the configuration file and its permissions. | | `11` | The credential is missing or rejected. | Run `linger-computer login`. | | `12` | The network failed. | Check that the Computer can reach the server. | | `13` | No Runtime is ready, or the named one is `NOT_INSTALLED`. | Install the Runtime, or pass its path. | | `14` | A capability check failed, such as an `INCOMPATIBLE` Runtime. | Update the Runtime. | | `15` | The Daemon failed to start, stop, or restart. | Read the Daemon logs. | | `16` | A `daemon runners` command failed. | Check the agent ID and the Daemon status. | ## A desktop action returns a `COMPUTER_` error The Computer Daemon returns a named error when it cannot send input safely. Most errors mean the agent sent nothing. | Error | What it means | What to do | | - | - | - | | `COMPUTER_BUSY` | Another task held the screen, and this call was cancelled while it waited. | Let the other task finish. | | `COMPUTER_USER_TOOK_OVER` | On a Mac, you brought another app forward. The agent does not take the screen back. | Ask the agent to continue when you are done. | | `COMPUTER_INPUT_PARTIAL` | The front app changed during typing. The result gives the number of characters typed. | Check the text before the agent continues. | | `COMPUTER_DESKTOP_LOCKED` | The screen is locked, on Windows or on the macOS lock screen. | Unlock the screen. | | `COMPUTER_SESSION_NONINTERACTIVE` | On Windows, the Daemon runs outside your signed-in desktop session. | Run the Daemon in your desktop session. | | `COMPUTER_PERMISSION_REQUIRED` | On a Mac, Accessibility or Screen Recording is not granted. On Windows, UI Automation is not available, and the Daemon does not elevate. | On a Mac, the agent runs `teamhub computer permissions request` and you grant access from the card. On Windows, the window tools stay unavailable on that Computer, and the Daemon does not elevate to get them. Browser and file tools still work. | `linger-computer doctor` does not check these OS permissions. On Linux, the desktop tools need an X11 session and the packages `python3-pyatspi`, `xdotool`, ImageMagick, and `xclip`. Under Wayland or with a missing package, the agent's permission check explains why. Browser and file tools still work. ## Switching accounts leaves a folder on Windows On Windows, a program can keep a file open inside the Computer's state folder. An example is an editor that an agent opened in its workspace. `linger-computer login` then leaves that folder in place, warns with its path, and completes the sign-in. `linger-computer doctor --prune` deletes everything, so it stops and names the open file. Close that program, then run the command again. ## Other computers cannot connect The server still listens only on `localhost`. Set the four network variables in `.env`, then run `docker compose up --detach --wait` again. [Serve other computers on your network](https://docs.heylinger.com/admin/network.md) lists the variables. ## The microphone is blocked Browsers allow the microphone only on `localhost` or HTTPS. Put an HTTPS proxy in front of port 3000, then open Linger through the HTTPS address. [Enable voice](https://docs.heylinger.com/admin/voice.md) covers the voice keys. ## `pnpm dev` cannot reach the database `pnpm dev` starts no containers. It migrates the PostgreSQL that `TEAMHUB_DATABASE_URL` names. The default value matches the `postgres` service of the root `docker-compose.yml`. Start that service first, then start Linger: ```bash theme={null} docker compose up --detach --wait postgres pnpm dev ``` In a second terminal, check every service: ```bash theme={null} pnpm dev:check ``` ## Keep learning > [card] [CLI reference](https://docs.heylinger.com/reference/cli.md) > > See every `linger` and `linger-computer` command. > [card] [Choose a runtime](https://docs.heylinger.com/models/choose-a-runtime.md) > > Install and sign in to Claude Code, Codex, or Pi. > [card] [Serve other computers on your network](https://docs.heylinger.com/admin/network.md) > > Open the server to your network safely. > [card] [Computer permissions](https://docs.heylinger.com/security/computer-permissions.md) > > Connect a Computer and control its agents. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.