# 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-commands` and 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](production-deployment.md).

## 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](https://github.com/mannders00/reticle/issues) for Desktop bugs or
[Discord](https://discord.gg/x6hY9GYyph) for questions.
