Skip to content

Troubleshooting

Protect running work first. A client display problem is not a reason to immediately delete a terminal, history, endpoint, or credential. Identify whether the failing layer is the client, daemon, authorization, or route.

Quick diagnostic

anytty --version
anytty config validate
anytty config paths
anytty daemon doctor
anytty daemon status
anytty endpoint list

For a remote endpoint, test routes independently:

anytty endpoint show ENDPOINT
anytty endpoint test ENDPOINT --route ROUTE

endpoint list only reads the local registry; endpoint test dials a route and verifies AnyTTY protocol reachability.

Command not found

Open a new shell, verify that the installer destination is on PATH, and use Get-Command anytty in PowerShell. Run the binary by absolute path to separate an installation failure from a PATH issue. Never bypass a failed release checksum; download again and check whether a proxy replaced the response.

Daemon startup and connection

anytty daemon doctor
anytty daemon status
anytty daemon logs --lines 200

Fix ownership as the current user instead of starting as root. Validate configuration for unknown fields or ranges. When service state is unclear, stop the background instance and use daemon run to observe foreground errors; do not run both. After an upgrade, verify the binary path and version so the CLI and service are not mixed.

TUI display and input

  • Enlarge the host terminal before diagnosing collapsed panels.
  • Check UTF-8, color, and mouse support; try a different host palette or disable mouse temporarily.
  • Inspect custom shortcuts. Declaring a scene replaces that scene’s default bindings.
  • Use terminal resize for a stuck size and check whether another client owns resize authority.
  • Nested TUI use is blocked by default. Set ANYTTY_ALLOW_NESTED=1 only when the recursive interaction is intentional.
  • Validate authoritative content with terminal capture or history search; a damaged Live view does not prove history loss.

Pairing

Claims expire after 10 minutes by default and are one-time. Generate a new claim, check device clocks, and use pair inspect locally to review metadata. A broader re-import is rejected unless --allow-scope-expansion is explicit. If one terminal or file is denied after pairing, inspect grant scope instead of recreating the route. Revoke a lost client with access list and access revoke.

Route failures

  • Local: check daemon status, resolved socket path, and that CLI and daemon run as the same OS user.
  • SSH: verify the system SSH login, key, proxy jump, and host key first. Default remote loopback ports are 127.0.0.1:41120 for signaling and 127.0.0.1:41121 for ICE-TCP. Investigate a pin mismatch instead of disabling validation.
  • Direct: verify the listener, host firewall, NAT, and enterprise network. Do not expose a wildcard listener to the public Internet merely for testing.
  • Cloud: inspect cloud status and cloud edge list; distinguish missing enrollment, a disabled runtime, failed P2P, and Relay plan or usage limits. Route success never expands a grant.

File failures

Confirm the endpoint, full path, daemon file policy, and grant. Do not enable overwrite without checking the target. Treat a checksum mismatch as an untrusted result. Preview failure does not prevent a verified download. For a healthy but slow large transfer, explicitly increase the default two-minute file operation timeout.

Redacted diagnostics

Include version, OS and architecture, minimal steps, expected and actual results, event time, command exit status, daemon status/doctor, relevant log lines, and route type. Remove private keys, claims, grants, Cloud tokens, addresses, hostnames, usernames, real paths, terminal output, and file contents. Never upload an entire config or history directory.

For general product questions, see Frequently asked questions. For unresolved failures, follow Releases and support and provide a minimal redacted reproduction.