Troubleshooting

Use this page to recognize what Traycer is telling you and what to do next. For how hosts work, see Hosts. Host controls are in Settings › Host › Overview.

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.
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. This device hasn’t confirmed it.
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) 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.
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.

Windows blocks the host start script

If startup reports EPERM or EACCES for host-start-hidden.vbs, or says Windows denied permission to create Traycer’s start script, security software may be blocking it. Allow Traycer’s data folder in your security software, then restart Traycer. The default folder is %USERPROFILE%\.traycer; if you moved Traycer’s data, use that folder instead. For Microsoft Defender, open Windows Security › Virus & threat protection › Manage settings. Under Exclusions, choose Add or remove exclusions › Add an exclusion › Folder, then select Traycer’s data folder.

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.
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. To find a Task, use History.

Updates

App updates. When a new version of Traycer is available, a download button appears in the header. See 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. Run traycer host status to see the last update result and any process currently holding the update lock. If another updater is active, traycer host update identifies it and waits up to 30 seconds; let it finish before trying again. An applied result means the files were installed, not that the Host answered; check status or run traycer host update to verify it comes back.

Data Folder Recovery

Run traycer data status if Traycer will not start during or after a data-folder move. It shows the selected folder, the move’s state, and the recovery command.

Interrupted move: run traycer data recover to continue. Before the location switch takes effect, traycer data recover --rollback can return to the old folder. After the switch, finish recovery; returning to the old location requires a new move.
Missing drive: reconnect the selected drive. Traycer does not silently use the default folder instead.
Agents held after a move: check the session-impact report. Start a new agent to keep working if the original cannot resume. If the Host’s relocation record cannot be read, run traycer data status.
Old copy still using space: after checking Traycer works from the new folder, use traycer data cleanup <migration-id>. It deletes the unused copy permanently and refuses if recorded content has changed.

See data folder commands. Do not delete or edit the move records in ~/.traycer-bootstrap or launch an older Traycer version against the backup.

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. 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). 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 <user>` 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	While the host is running, run `traycer login` as the host’s owner, or open Traycer Desktop signed in as the host’s owner and let it connect. Either replaces the credential.
Another Traycer CLI comes first on PATH	Follow the paths and versions in `traycer host doctor`: upgrade the package-manager copy or put the managed CLI first on PATH. If your shell runs an old CLI without this check, run the current managed CLI by its full path.
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 covers the desktop app.
CLI log level and Host log level in Settings › Host › Diagnostics cover the command-line tools and the host. They apply to every Traycer host on that machine.

To open the logs:

Choose Help › Open Logs, or Open Logs in the Traycer tray menu.
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.
Click Reveal to show the file in your file manager.

From a terminal on the host’s machine:

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.

Choose a type

Bug, Idea or Something else.

Describe it

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.

Choose what to attach

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.

Send it

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.

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.
`Clone this agent to continue while "{label}" is offline; the original stays there.`	Click Clone agent to continue on the active host, or open Traycer on the original host. Cloning creates a new agent and leaves the original where it was. With view-only access to the Task, the banner explains that cloning is unavailable and shows no Clone button.
`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.
`This agent belongs to {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.
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 <machine> 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.
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.

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.

Mobile Simulator Platform Still Unavailable

If Traycer still reports a missing simulator platform after you install its tools, open Settings › Host for that machine, then Mobile simulators. Click Check again beside Use mobile simulators when simulators are off, or on the Platforms row when they are on. The button appears when a platform is unavailable. It asks that host to look again and is disabled while the check runs. An unavailable simulator tile also offers Check 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, or set CURSOR_API_KEY in the host’s environment in 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 <provider> / 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 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:

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.
In Settings › Shell, 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.
Restart the host: ⋯ › Restart in 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 <version> (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.

Get Started

Guides

Concepts

Panels

Agents & Models

Account

CLI

Reference

Changelog

Host Status

Starting Traycer

Windows blocks the host start script

Missing Home Activity

Updates

Data Folder Recovery

Doctor

Logs

Report An Issue

Host-Bound Tabs

File Not Found In A Preview

Other Messages

Worktree Setup

Mobile Simulator Platform Still Unavailable

Provider Auth

Model Picker

Models Or Model Downloads Fail Behind Antivirus Or A Proxy

App Menus

​Host Status

​Starting Traycer

​Windows blocks the host start script

​Missing Home Activity

​Updates

​Data Folder Recovery

​Doctor

​Logs

​Report An Issue

​Host-Bound Tabs

​File Not Found In A Preview

​Other Messages

​Worktree Setup

​Mobile Simulator Platform Still Unavailable

​Provider Auth

​Model Picker

​Models Or Model Downloads Fail Behind Antivirus Or A Proxy

​App Menus

Host Status

Starting Traycer

Windows blocks the host start script

Missing Home Activity

Updates

Data Folder Recovery

Doctor

Logs

Report An Issue

Host-Bound Tabs

File Not Found In A Preview

Other Messages

Worktree Setup

Mobile Simulator Platform Still Unavailable

Provider Auth

Model Picker

Models Or Model Downloads Fail Behind Antivirus Or A Proxy

App Menus