Troubleshooting#

Start with the service-wide check, then narrow to the subsystem the check names. Preserve worktrees, events and provider output before you retry anything that can repeat an external side effect.

Start with doctor#

syndicate doctor
syndicate doctor --json

doctor reports one line per check. A fail sets a non-zero exit code; a warn does not. Failed and warned checks print the remediation command beside them.

--json returns schemaVersion and the checks array, each entry carrying an id, a status and a one-line summary. The output carries check results only — never prompts, tokens or transcripts.

Correct the first failed check — configuration, tmux or Host readiness — then verify again before launching a session.

An agent is unavailable#

Run syndicate agent list and read the state column. --json returns the full probe, adding the availability, sign-in, ownership and configuration fields that the one-line form omits.

Syndicate never reports a CLI as signed in on the strength of a successful exit alone. An unrecognisable answer is auth-unknown, so treat it as "ask the CLI", not as a working session.

Syndicate does not hold provider credentials and has no route that performs a login. The dashboard shows the exact sign-in command and opens a Host terminal for you to run it in; the CLI owns its own authentication.

A CLI installed while the Host is running does not need a service restart. The Host re-probes when a launch is refused, with a short negative window, so retry the pane after a few seconds.

A pane or session will not start#

Confirm the terminal runtime first. syndicate host status and the terminal-host service logs show whether the runtime is connected; restart the terminal-host service before investigating the adapter.

If the runtime is connected and the launch is refused for the adapter, re-read syndicate agent list for that agent and follow the table above.

Dashboard invitation fails#

Generate a new invitation; URLs are short-lived and single-use. Use the printed URL unchanged — the Host accepts its own loopback address and the configured dashboard origin, and rejects a browser that reaches it under any other name. Confirm the SSH tunnel reaches the loopback Host. Do not weaken Host binding or reuse a consumed URL.

If the dashboard loads but every action is refused, check the dashboard origin the Host is configured with. A Host pointing at an origin the browser is not reaching will serve the page and refuse the actions; re-run syndicate setup and reach the dashboard over an SSH tunnel to the loopback port.

A session is stuck#

Inspect service logs, session events and the provider process. Stop through Syndicate before using operating-system termination. Stopping a terminal session ends the whole process session it created, so a background command started inside a pane stops with it.

An exit Syndicate cannot prove is reported unconfirmed and its worktree stays quarantined. Preserve it for manual review rather than forcing a release.

A worktree cannot be released#

Run git worktree list, inspect the lease and preserve commits. Do not delete the directory until no provider process can still write and the branch is recoverable.

The terminal session list keeps growing#

Every converge that cannot start an agent leaves a durable failed row, so syndicate session list accumulates finished rows over time.

This release has no sweep for them, and no setting turns one on. The rows are small, and the exit code and failure reason are in the event log either way, so treat the growth as a disk-planning matter rather than a fault. Fix the reason a converge cannot start its agent — see the agent table above — so new rows stop arriving, and back up and replace the state directory when it becomes large. See Operations and upgrades.

When reporting an incident, remove invitation tokens, cookies, provider output, repository secrets, hostnames and private paths.