> ## Documentation Index > Fetch the complete documentation index at: https://docs.traycer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > What Traycer's status words, startup screens and messages mean, how to collect logs, and how to report an issue. Use this page to recognize what Traycer is telling you and what to do next. For how hosts work, see [Hosts](/concepts/hosts). Host controls are in [Settings › Host › Overview](/settings/host). ## Host Status Each host shows a status word in the host picker and in its Overview header. | Status | Meaning | | - | - | | **Online** | The host is running and reachable. "Connection is unstable." means the connection keeps dropping. | | **Restarting…** | The host is restarting on purpose, for example after an update. The app reconnects on its own. | | **Offline** | The host can't be reached. The detail says when it was last seen. | | **Stopped** | Traycer is installed on this computer, but the host isn't running. Restart it or run [Doctor](#doctor). | | **Not installed** | No Traycer host is installed on this computer yet. | | **Update required** | The host runs an older version than this app supports. Click **Update host**. | | **Removed** | The host was removed from your account. | | **Reported reachable** | Your account heard from the host recently, but nothing on this device has connected to it yet. | | **Status unknown** | The host hasn't reported to your account yet, or its live status is unavailable right now. | | **You're offline** | This device has no connection, so it can't check the host. | If a host can't check for updates, its Overview's Updates tab shows **Update check failed** with the reason. Click **Check now**, next to **Pick a different version**, to try again. ## Starting Traycer While Traycer starts, it shows **Starting Traycer…**. When the host on this computer has work to do first, the line changes to what it is doing, such as **Downloading Traycer Host…**, **Setting up Traycer Host…**, **Installing Traycer Host…** or **Applying the host update…**. If startup needs your attention, a card explains why: | Card | Meaning | What to do | | - | - | - | | **Setting up Traycer** | First launch on this machine. "This runs once, and the app opens as soon as it's done." | Wait. | | **Traycer Host didn't start** | The host on this computer failed to start. The card shows each attempt and the startup log. | **Retry**. If it keeps failing, **Open settings** (for example to change the shell in [Shell](/settings/shell)) or **Report issue**. | | **No host is available** | "Traycer can't reach any of this account's hosts right now. It will connect again on its own as soon as one comes back." | Wait, or check that a host machine is on and connected. | | **Update Traycer to continue** | The host needs a newer version of the app. | Update the app. See [Updates](/install#updates). | | Host update required | The host is too old for this app. | **Update host**. For a host on another machine, update Traycer on that machine. | | **Traycer was removed** | You removed Traycer's background components from this computer. | **Quit Traycer** to finish uninstalling, **Reinstall**, or **Open settings** to use another host. | Every card offers **Open settings**. **Retry** and **Report issue** appear once something has failed. ## Missing Home Activity **Some activity may be missing** on the **Home** tab means Home can't see every running Task right now. When only some of your machines are affected, the notice sits under that machine's heading. A line under the notice names each affected machine and why, worst first: | Line | What it means | | - | - | | Lost connection to *host*. Its tasks aren't shown. | This app's connection to that host is down, so that host's Tasks are left out until it reconnects. | | Reconnecting to *host*… | That connection is coming back. | | *host* isn't connected to Traycer, so tasks from your other machines may be missing. | That host's own Tasks still show. Activity from your other machines reaches Home through the host's link to Traycer, and that link is down. | | *host* is reconnecting to Traycer, so tasks from your other machines may be missing. | The same, while the link comes back. | When no machine has reported yet, the line is about your sign-in instead: | Line | What to do | | - | - | | You're signed out, so running tasks can't be loaded. | Sign in. See [Sign In](/account/sign-in). | | Signing in… | Wait. | | Can't reach Traycer to confirm your sign-in, so running tasks may not load until it can. | Check your connection. Running Tasks load once Traycer can be reached. | | Your session has expired. Sign in again to see running tasks. | Sign in again. | | This account is no longer available, so running tasks can't be loaded. | Sign in with another account. | | This window's session was ended from another window, so running tasks can't be loaded here. | Sign in again in this window. | | Connecting to your machines… | Wait. | A Task missing from Home hasn't been deleted. To check a machine, see its [status](#host-status). To find a Task, use [History](/concepts/history). ## Updates **App updates.** When a new version of Traycer is available, a download button appears in the header. See [Updates](/install#updates). **Host updates.** The update card on a host's Overview reports progress. If an update is waiting, it says why: | Message | Meaning | | - | - | | "Update waits for N sessions to finish" | The host applies the update when its running agents and terminals finish. **Force update…** ends them now. | | "Update waits for Traycer's command-line tools to be updated — see installation help" | The update needs newer command-line tools first. The **Updates** tab shows the command to run. | | "Update installed — restart host to finish" | Click **Restart** to start the new version. | If you restart or update a busy host, a **Host is busy** dialog names what is still running. Choose **Defer** to wait, or **Force restart** / **Force update** to end that work now. ## Doctor Doctor checks a host's installation, service, port and credentials. Run it from **Settings › Host › Overview › ⋯ › Run doctor**, or with `traycer host doctor` on the host's machine. The fix buttons are described in [Overview](/settings/host#doctor). Common issues: | Issue | What to do | | - | - | | **Host not installed** | **Install host**, or run `traycer host install`. | | **Service not registered** | **Register service**, or run `traycer host service install`. | | **Service registered but host stopped** | **Start host**, or run `traycer host restart`. | | **Host port held by another process** | **Free port + restart** asks that process to exit and restarts the host. | | **Host endpoint unreachable** | **Restart host**. | | **systemd user manager unreachable** | Linux only. The host needs a systemd user session. In WSL, enable systemd (see [Windows via WSL](/install#windows-via-wsl)). On a headless machine, log in through a systemd session or enable lingering. | | **Host stops at logout (lingering disabled)** | Linux only. Run `loginctl enable-linger ` so the host keeps running after you log out. | | **Host service is failing to start** | Linux only. The card gives a `journalctl` command that prints why the service failed. | | **Host rejected the stored credentials** | Run `traycer login`. | | **Host credential needs re-authorization** | Open Traycer Desktop, signed in as the host's owner, and let it connect. It replaces the credential on its own. Signing in again doesn't fix this. | | **Service managed by Traycer Desktop** | Not a problem. Traycer Desktop manages this host's startup on macOS. | ## Logs Before you reproduce a problem, raise the log level to **Debug**, then set it back afterwards: * **App log level** in [Settings › Application › Diagnostics](/settings/diagnostics) covers the desktop app. * **CLI log level** and **Host log level** in [Settings › Host › Diagnostics](/settings/host-diagnostics) cover the command-line tools and the host. They apply to every Traycer host on that machine. To open the logs: 1. Choose **Help › Open Logs**, or **Open Logs** in the Traycer tray menu. 2. In the **Open Logs** dialog, expand **Desktop Log** or **Host Log** to preview recent output. In-app browser logs are listed too when there are any. 3. Click **Reveal** to show the file in your file manager. From a terminal on the host's machine: ```bash theme={null} traycer host logs --tail 200 ``` Use `traycer host logs --follow` to stream new lines. The host log is `~/.traycer/host/host.log` and the CLI log is `~/.traycer/cli/cli.log`. ## Report An Issue Open **Report an issue** from **Help › Report Issue**, **Report issue** in the command palette, or the **Report issue** button on an error card or toast. **Bug**, **Idea** or **Something else**. Answer the main question, such as "What were you trying to do, and what went wrong?" for a bug, and set **Where did this happen?** if the dialog asks. For a bug, also choose **How often?**: **Once**, **Sometimes**, **Every time** or **Not sure**. Paste or drop screenshots if they help; they stay private. **App log tail** and **Host log tail** attach the end of each log. They start on for a bug and off for other types; you can change either. **Browser diagnostics** appears when in-app browser logs exist. Click **Send report**. The report goes privately to the Traycer team, and you get a report ID to copy. New reports get a first look within 1 business day. **Post it on GitHub too.** After sending, click **Also post publicly on GitHub**, then review **Preview the public issue**. Logs, stack traces and identifiers stay in the private report. **Open GitHub draft** opens the issue in your browser; nothing is posted from the app. **Offline.** "You're offline, so your report is saved on this machine - it will be sent automatically when the connection returns." **When private reporting isn't available**, the dialog offers **Save diagnostic bundle** and **Open a GitHub issue**. The bundle contains scrubbed logs; review it before you share it publicly. ## Host-Bound Tabs Every tab belongs to the host it was opened on. See [Tabs and their host](/concepts/hosts#tabs-and-their-host). | Message | Meaning | | - | - | | `Host "{label}" is unreachable. This terminal is permanently closed.` | A terminal can't move to another host. Close the tab and open a new terminal. | | `Host "{label}" is unreachable, so this agent is unavailable until that host is back.` | An agent on the Terminal interface stays on its host. The agent and its transcript are kept; closing the tab only removes it from the canvas. | | `This agent is not running on "{label}" right now, and it can only be started on that machine.` | An agent on the Terminal interface on another machine isn't running. Start it from that machine. | | `Bound host "{label}" is offline. Continuing here creates a new agent on the active host; this one stays bound to "{label}".` | An agent on the Chat interface. Continuing clones it onto the active host; the original stays where it was. With view-only access to the Task, it can't be cloned. | | `This agent lives on {host}, which is offline — showing the last published copy. Sending resumes when that host is back.` | You're reading a read-only copy. See [Sync and offline](/concepts/sync-and-offline). | | `This agent belongs to another collaborator, and its history isn't available here.` | A shared agent whose live history isn't on this host. The tab may show its last published copy, and cloning creates your own agent on the active host. | | `This agent is no longer shared with you.` | Access was removed while the tab was open. | | `This file is on host "{label}", which is currently unreachable.` | The file preview loads once that host is back. | | `This diff is on host "{label}", which is currently unreachable.` | The diff loads once that host is back. | | `Waiting for the host to start…` | The tab's host is starting or restarting. The tab continues on its own. | ## File Not Found In A Preview An image, PDF or Word preview shows **File not found**, with the file's name and "It may have been moved, renamed or deleted.", when its file is no longer on disk. The toolbar above it still shows the file's path. There's no **Open Externally**, because there is no file to open. * **The file moved or was renamed:** open it again from its new place, for example from the [File Tree](/panels/file-tree). * **You put it back at the same path:** click into another pane and back. The preview checks the file again each time its pane regains focus. This is different from a file Traycer can't preview, which still offers **Open Externally** when the file exists. ## Other Messages | Message | Meaning and what to do | | - | - | | **System clock is incorrect** | A banner reads "Your system clock appears to be …". If your clock is ahead, Traycer can't connect until it's corrected; if it is behind, times in the app are wrong. Set your system clock to update automatically. | | **Authorize background work** | "Enter the code sent to your email so \ can keep running your work after you disconnect." Enter the 6-digit code from your email and click **Verify**. **Resend code** sends a new one. | | **Finish updating Traycer** | Linux only. The update was downloaded but this install can't apply it automatically. Run the command shown, then restart Traycer. See [Updates](/install#updates). | | **Rebind local store** | Creating a Task failed because the host's local store isn't available. **Rebind local store** claims the data folder for this host; first make sure no other Traycer host uses it. If the host can't repair it from here, follow the steps in the dialog on that machine. | ## Worktree Setup When an agent runs in a new worktree, its chat shows a setup card. See [Setup and teardown scripts](/concepts/worktrees/scripts). | State | Meaning | | - | - | | **Creating worktree** | Git is creating the worktree. | | **Setting up worktree** | The setup script is running. It has no overall time limit, but it is cancelled after 5 minutes with no output. | | **Worktree ready** | The worktree was created and setup finished. | | **Setup failed** | The setup script exited with an error, shown as "(exit N)". Click **Retry setup**. | | **Setup cancelled** | Setup was stopped: Ctrl+C, the setup terminal was closed, or 5 minutes passed with no output. Click **Retry setup**. | | **Worktree creation failed** | Git couldn't create the worktree. Click **Retry creation**; queued messages resume after it succeeds. | | **Worktree setup incomplete** | An earlier setup never reported a result, for example because the host stopped. It isn't running and can't be retried. | The agent's first message waits for setup, but still runs if setup fails. With several folders, the card reads "Setting up N worktrees", "N of M done" or "Worktree setup failed". If a workspace folder no longer exists or can't be reached, choose an available folder and try again. ## Provider Auth | State | Meaning | | - | - | | **Checking account…** | Traycer is checking the provider account. | | **Not authenticated** | The provider needs a login, an API key or CLI sign-in. | | **API key set** | A required key is configured. | | **Account status unavailable** | Traycer couldn't confirm the provider's status. | For Cursor, add the Cursor API key in [Settings › Providers](/settings/providers), or set `CURSOR_API_KEY` in the host's environment in [Shell](/settings/shell). ## Model Picker | State | Meaning | | - | - | | **Loading models** | Traycer is loading the model list. | | **Couldn't load providers** | The provider list failed to load. | | **Couldn't load models** | The model list failed to load for the selected provider. | | **No models available** | The selected provider returned no usable models. | | **No models match** | Your search filtered out every model. | | **Connect \** / **Add API key** | The provider needs an API key. **Add API key** opens its settings. | If a provider is missing from the picker, it may not be installed or configured on that host. ## Models Or Model Downloads Fail Behind Antivirus Or A Proxy If a provider's model list never loads or a model download fails, and a browser or `curl` reaches the same address fine, your antivirus or company proxy may be inspecting secure (HTTPS) connections with its own certificate. Traycer doesn't recognize that certificate, so it refuses the connection. The [host log](#logs) reports the model list or the download failing, and if the log names a certificate error such as `SELF_SIGNED_CERT_IN_CHAIN`, this is the cause. To fix it: 1. Export the security software's root certificate as a PEM file (`.pem` or `.crt`). Your antivirus or IT team can tell you where it is. 2. In [Settings › Shell](/settings/shell#host-environment), under **Host environment**, click **Add environment variable**, enter `NODE_EXTRA_CA_CERTS` as the **Name**, choose **Set**, and enter the full path of the file on the machine the host runs on. 3. Restart the host: **⋯ › Restart** in [Settings › Host](/settings/host). For a remote host this is the route to use, because **Help › Restart Host** and the tray menu's **Restart Host** restart only this computer's host. If the host is busy, a dialog names the running work and lets you defer the restart. Traycer keeps trusting its normal certificates. Traycer, and the agents it runs, then also trust every site that certificate's authority vouches for. ## App Menus **Help menu:** **Documentation**, **Release Notes**, **Report Issue**, **Open Logs**, **Restart Host**, **Check for Updates** and **About Traycer**. **Tray menu:** **Open Traycer**, your recent Tasks, **Settings…**, **Update to \** (when a host update is available), **Check for Updates**, **Restart Host**, **Open Logs**, your account with **Sign In** or **Sign Out**, and **Quit Traycer**. On macOS, the **Traycer** menu also holds **Settings…**, **Sign In** / **Sign Out**, **Restart Host** and **Check for Updates**. On Windows and Linux, **Settings…** and **Sign In** / **Sign Out** are in the **File** menu. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.