Troubleshooting
Start with the symptom, the active workspace path, and whether you are using Desktop, a Team editor/viewer session, or the static demo. The status bar identifies the runtime and, for Team, the role.
A node stays unknown#
Entering a host and port does not create a check. Open the Inspector and add a check under Checks → + add, then Save operations. Confirm it is enabled. Custom checks also need privileged mode on Desktop or daemon command policy on Team. A group with no descendant signals remains unknown.
An HTTP check fails#
Read the check's detail in the Inspector. Verify that the Reticle host can reach
the URL and find curl on its process PATH. A JSON predicate needs jq too.
Try the same URL from that host. For Team this is the daemon machine, not your
laptop. Check DNS, proxy settings, TLS certificates, redirect destinations, and
the expected status. Quote exact status codes in YAML, for example status: "200".
A jq predicate must succeed under jq -e.
SSH fails or waits for authentication#
Fixed checks and named actions use non-interactive SSH (BatchMode=yes) with
the node's explicit user and port. Confirm the same OS identity running Reticle
has a working key/agent, SSH config, and known-hosts setup. Do not assume an SSH
agent from your interactive login is available inside a systemd service.
The SSH service check uses systemctl is-active; it requires a systemd service
on the remote host. HTTP checks may be a better fit for other platforms.
Check, Run, or editing is unavailable#
- A Team viewer cannot save, refresh, use chat, or invoke actions.
- A changed Inspector draft disables Check/Run/Shell until Save details or Discard.
- Custom choices require Enable privileged mode on Desktop, or
--allow-custom-commandsand an editor session on Team. - A named action may require a particular signal state. Read its unavailable reason and collect fresh evidence.
- Local Bash commands and interactive terminals are unavailable on Windows. Team has no browser terminal on any platform.
Changes are not saving#
Check whether you are a viewer or using a static demo: neither persists edits. Canvas changes autosave; Inspector details and operations use their own Save buttons. Check filesystem permissions and the path in the status bar.
A conflict means the file changed while your local edits were pending, or a Team save used an old revision. Reticle preserves the draft but does not merge it. Record the changes you need before reloading; then reapply them to the latest file. A PDF is a visual reference, not a YAML backup.
A workspace will not switch#
Save or discard open Inspector forms and wait for running actions to finish. If a recent file says it is missing, open its new location. Removing a recent entry does not remove the file.
Team says disconnected or access denied#
After a daemon restart or network interruption, reload the page to reconnect. The client does not automatically reconnect; displayed health may be stale. Use the correct viewer/editor token. A wrong token is denied rather than silently downgraded to anonymous viewing. If a token was rotated, use a new link or clear the site's session storage before reconnecting.
For operators, test TLS/proxy WebSocket forwarding and the daemon's
/health/live and /health/ready endpoints. Readiness can fail while a fresh
graph is unavailable or the configured audit log is unhealthy. It does not mean
every monitored service is healthy. See production deployment.
The API differs from the Desktop window#
Desktop's loopback API and chat run fixed checks with custom execution disabled. The trusted window can run custom checks, so their signals and action availability may differ. Team API/MCP clients read the daemon's cached graph. Group health rollups belong to the UI and are not extra API signals.
An embedded page is blank#
Use an absolute HTTP(S) URL without embedded credentials. The remote site can
block framing with CSP or X-Frame-Options. Reticle's sandbox also restricts
browser capabilities and cookie-dependent applications may not work. The page
must be reachable from the viewing browser; open it separately if needed.
Get help#
Include the Reticle version, operating system, runtime/role, exact error, and the smallest reproduction you can share. Remove tokens, credentials, and private infrastructure details from examples. Use GitHub issues for Desktop bugs or Discord for questions.