# Troubleshooting (/docs/v0.4/remote/troubleshooting) Start with `koshi doctor` on the machine holding the sessions. Its `remote access` and `remote connections` rows say whether the listener has an address, how many grants stand, and how many connections are open. ## Nothing is listening on that port [#nothing-is-listening-on-that-port] ```text koshi: IPC unavailable: laptop.local:7654 refused the connection: nothing is listening on that port. if remote access is not enabled on that machine, run `koshi share grant` there and answer yes to the offer to open the port ``` Work through these on the **server**, in order: 1. `koshi.kdl` has no `remote-listen` line. Add one and grant again. 2. The line is there, but nobody answered the offer with `y`. Run `koshi share grant` again and type `y`. 3. Another program holds the address. `koshi share grant` says so: ```text remote access is on, and nothing is listening on 0.0.0.0:7654: another program holds it. Free that address, then run `koshi share grant` again to open the port. This token cannot be used to connect until then. ``` 4. The machine's firewall, or a cloud security group in front of it, drops the port. koshi touches neither. ## The certificate is not the pinned one [#the-certificate-is-not-the-pinned-one] The refusal names the address and both fingerprints. The machine answering that address is not the one you pinned. When the server really was reinstalled: ```bash koshi remote forget work koshi list-sessions --remote work # pins the certificate it meets ``` When you do not know why it changed, stop and find out first. ## The saved secret was refused [#the-saved-secret-was-refused] ```text work: the saved secret was refused; run `koshi remote set-secret work` ``` The grant expired, was revoked, or was replaced by a newer grant to the same identity on the same scope. Get a fresh token on the server: ```bash koshi share grant alice # server koshi remote set-secret work # client ``` ## The token does not reach that session [#the-token-does-not-reach-that-session] The token is session-scoped and names a different session. Either attach to the session it reaches, or grant one that reaches this one: ```bash koshi share list --session quiet-lake # who can get into this session koshi share grant alice --session quiet-lake ``` ## The two builds share no protocol version [#the-two-builds-share-no-protocol-version] The terminal and the session speak a protocol with a version, and each build speaks a range. When the ranges do not overlap the connection is refused, naming what each side speaks. Nothing is drawn and nothing is changed. Install the same koshi release on both machines. See [Version compatibility](/docs/v0.4/using/attach-and-detach#version-compatibility). ## The link keeps dropping [#the-link-keeps-dropping] A refusal no dial can change stops the dialing at once — a certificate that is not the pinned one, a token the server does not admit, a token that does not reach the session, or two builds sharing no protocol version. koshi names the cause and prints the commands that list and rejoin the session. Everything else dials again for up to 120 seconds. See [Reconnecting](/docs/v0.4/remote/servers#reconnecting). ## `--remote` was refused [#--remote-was-refused] ```text --remote works with `attach`, `list-sessions`, and the action verbs, such as `koshi attach --remote ` ``` `--remote` never creates a session, and `koshi share` and `koshi doctor` always run on the machine they are about. Run those on the server itself. ## `koshi share` was refused inside a pane [#koshi-share-was-refused-inside-a-pane] ```text koshi: command not permitted someone is attached to this session from another machine, and they see this pane. Run `koshi share` from a terminal outside koshi. ``` The session paints that pane to every client viewing its tab, including the remote one, so a token would print onto their screen. Run the verb from a terminal outside koshi, or detach the remote client first. See [Run these outside koshi](/docs/v0.4/remote/tokens#run-these-outside-koshi). ## Another koshi is changing the saved servers [#another-koshi-is-changing-the-saved-servers] ```text koshi: IPC unavailable: another koshi is changing the saved servers; try again ``` A second `koshi` held the store lock for more than five seconds. Run the command again. The operating system releases the lock if the `koshi` holding it dies. ## A saved server never shows up in the sweep [#a-saved-server-never-shows-up-in-the-sweep] A saved server that pins no certificate is left out of the sweep that a bare `koshi list-sessions` and a bare `koshi attach` make, and one stderr line names it. Name it once to pin its certificate: ```bash koshi list-sessions --remote work ``` A server that does not answer inside the two-second sweep is also left out. Name it to wait for it properly. ## Exit codes [#exit-codes] `--remote` does not change what a verb exits with; the codes are the verb's own. | Command | Code | Meaning | | ---------------- | ---- | --------------------------------------------------------- | | `kill-session` | `3` | Unknown session name or id | | `kill-session` | `4` | The control socket could not be reached | | `server-version` | `4` | A server could not be asked; the other rows still printed | | `doctor` | `1` | The run holds a `fail` row | Every refusal on this page exits non-zero and prints its cause on standard error.