Troubleshooting

Start with koshi doctor on the machine holding the sessions. Its remote access, remote listener, and remote connections rows say whether koshi.kdl names a listen address, how many grants stand, which address the router serves and with which certificate fingerprint, and how many connections are open.

Nothing is listening on that port

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 open` there to open the port

Work through these on the server, in order:

1. koshi.kdl has no remote-listen line. Add one, run koshi restart-servers, then koshi share open.
2. The line was added or changed while the router ran. The remote listener row of koshi doctor warns and names koshi restart-servers. Run it, then koshi share open.
3. The port was never opened. Run koshi share open.
4. Another program holds the address. koshi share open prints the router's reason and exits 1. Free the address and run it again.
5. The machine's firewall, or a cloud security group in front of it, drops the port. koshi touches neither.

The certificate is not the expected one

koshi: IPC unavailable: the certificate laptop.local:7654 presented is not the expected one: expected sha256:3f6a0c2e9b8d4f17a5c3e1d0b9f8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0, presented sha256:0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c. the secret was not sent. if that machine's certificate changed on purpose, `koshi share open` there prints the new fingerprint: give it with `koshi remote edit work`

The machine answering that address presented another certificate, and the secret was not sent. When the server's certificate changed on purpose, run koshi share open on the server to print the new fingerprint, then koshi remote edit work on the client to store it. When you do not know why it changed, stop and find out first.

The fingerprint is missing or does not match

koshi: invalid arguments: laptop.local:7654 is not saved, so the fingerprint of its certificate is needed: add `--certificate-fingerprint <FINGERPRINT>` with the fingerprint `koshi share grant` printed on that machine

An address that is not saved needs --certificate-fingerprint. Use the connect command koshi share grant or koshi share open printed on the server.

A saved server refuses a --certificate-fingerprint other than the one it holds, and names koshi remote edit <SERVER>. A saved server that holds no fingerprint is not dialled; run koshi remote edit <SERVER> and give one.

The server did not admit the connection

koshi: work: the server 192.0.2.10:7654 did not admit the connection: the token expired, was revoked, or was never granted on that machine, or that machine already serves as many remote connections as it admits. `koshi share list` on that machine shows when each grant expires or was revoked. to replace the token, run `koshi share grant` there, then store the new secret with `koshi remote set-secret work`; its sessions are not listed

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:

koshi share grant alice          # server
koshi remote set-secret work     # client

The connection closed during the TLS handshake

A serving machine closes a connection before the handshake finishes when its koshi restarts or stops, when 64 other connections wait to present a secret, and when the address the connection comes from opened 10 connections in 60 seconds that were not admitted. Dial again in 60 seconds. If it keeps happening, run koshi doctor on that machine.

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:

koshi share list --session S-quiet-lake   # who can get into this session
koshi share grant alice --session S-quiet-lake

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.

The link keeps dropping

A refusal no dial can change stops the dialing at once — a certificate that is not the expected 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.

--remote was refused

--remote works with `attach`, `list-sessions`, and the action verbs, such as `koshi attach --remote <server>`

--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: 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.

Another koshi is changing the saved servers

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 that holds no certificate fingerprint is left out of the sweep that a bare koshi list-sessions and a bare koshi attach make, and one stderr line names it. Give it a fingerprint:

koshi remote edit 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

--remote does not change what a verb exits with; the codes are the verb's own.

Every refusal on this page exits non-zero and prints its cause on standard error.