Skip to main content

TUI Cannot Connect

Symptoms​

  • flowlayer-client-tui fails to connect.
  • connection opens then immediately fails with auth status.
  • /health returns 401 or 403.

Likely causes​

  • server Session API is disabled (no -s and no session.bind)
  • wrong -addr value
  • wrong -token value
  • using a server-only config in TUI -config mode with no session.addr
  • remote host is not reachable from your client machine

Resolution​

  1. Confirm server session mode is enabled:
flowlayer-server -c ./flowlayer.jsonc -s 127.0.0.1:6999 -token dev-token
  1. Validate health from the same machine as the TUI:
curl -H "Authorization: Bearer dev-token" http://127.0.0.1:6999/health

Expected response:

{"ok": true}
  1. Connect with explicit parameters first:
flowlayer-client-tui -addr 127.0.0.1:6999 -token dev-token

  1. If you use -config, ensure the file contains session.addr for the client.

  2. For remote servers, tunnel first, then connect locally:

ssh -N -L 6999:127.0.0.1:6999 dev@remote-host
flowlayer-client-tui -addr 127.0.0.1:6999 -token dev-token

Status code meaning​

  • 401 Unauthorized: missing Authorization header
  • 403 Forbidden: header exists but token does not match

See Remote Access and Session Token.