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

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:

   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 refusal names the address and both fingerprints. The machine answering that address is not the one you pinned.

When the server really was reinstalled:

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

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:

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

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 quiet-lake   # who can get into this session
koshi share grant alice --session 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 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.

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

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

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