--- url: https://cuonghuunguyen.github.io/reference/troubleshooting.md description: >- Fixes for common claude-code-ui problems (node-pty install errors, pairing, ports, WSL and Docker sides, push, updates) and answers to frequent questions. --- # Troubleshooting & FAQ ## Something is wrong ### `npm i` fails on `node-pty` (Linux, WSL) The terminal panel needs a C++ toolchain. On Debian or Ubuntu: ```sh sudo apt install build-essential python3 ``` ### The browser keeps asking to pair Open the pairing link the daemon printed at start (it ends in `#token=…`). On an iPhone Home Screen app, paste that link into **Pairing link or token** and tap **Pair**. iOS can clear the app's storage after weeks without use; pair again then. ### "This daemon does not accept that token" The token changed (the `token` file was deleted, or you use a different config folder). Copy the link the daemon printed last. ### Port in use Start on another port: `claude-ui --port 4281`. ### WSL or Docker side "stopped (exit code 1)" In 0.5.0 every WSL and Docker side stops about 15 seconds after it starts. This is a known bug: [#263](https://github.com/cuonghuunguyen/claude-code-ui/issues/263). **Retry** starts it again, but it stops again. Windows and local projects are not affected. ### The side needs Node.js or build tools The Open project dialog says what is missing. A WSL distro or Docker container with glibc (Debian, Ubuntu, ...) needs only `sh`, `tar` and `gzip` (a WSL distro also `bash`): claude-code-ui uses a Node.js 22+ found there, else brings its own. A WSL distro that installs with npm (musl, see below) needs Node.js 22+, make, python3 and g++. Open **What this container needs** in the dialog for the list with a ✓ or ✗ per item. The dialog does not check the Claude login: a session started without one says so. See [WSL & Docker](../features/wsl-docker). ### A Docker container or WSL distro installs with npm, not the bundle The dialog says why. Causes: * The container or distro uses musl (Alpine) or a CPU other than x86_64 and arm64, has glibc older than 2.28, or has no libstdc++. Use a glibc image or distro, or install Node.js 22+, make, python3 and g++ there. * Your computer could not download a part (Node.js from nodejs.org, only for a target without Node.js 22+; node-pty, the Claude Agent SDK or Claude Code from the npm registry) and has no checked copy in `~/.cache/claude-ui/side`. Check the network or set `CLAUDE_UI_UPDATE_REGISTRY` to a registry mirror, then retry. * `docker exec` could not run in the container (stopped meanwhile, no `sh`, runtime error): the reason quotes the error. Parts of an older claude-ui version stay in the cache for 7 days after their last use, then are removed. A downloaded or cached part that does not match its checksum is never used: it is downloaded again. ### Push notifications do not work * The page must be on HTTPS (or `localhost`). Use [`--tailscale`](../features/remote-access). * On iPhone/iPad: iOS 16.4+, and the app must be on the Home Screen. * Without HTTPS, the daemon's computer shows desktop notifications instead (Linux needs `notify-send`, package `libnotify-bin`). ### A new version does not start claude-code-ui falls back to the previous version and says so. See [Updates](../features/updates). ### `--tailscale` exits right away It prints what is missing: Tailscale not installed or not logged in, MagicDNS or HTTPS certificates off, the machine not approved, or Funnel on. On Linux without root, run `sudo tailscale set --operator=$USER` once. On Windows with WSL, run `--tailscale` on Windows, not inside WSL. ## FAQ ### Do sessions stop when I close the browser? No. They run in the daemon. Open the page again to catch up. ### Do sessions stop when I stop the daemon? The running turn stops. The session and its history stay, and you can continue it after the next start. ### Does it work with sessions from the `claude` CLI? Yes. Both read and write the same history in `~/.claude`. A session started in one shows up in the other. ### How do I unpair all browsers? Delete the `token` file in the [config folder](cli#files) and restart. Every browser must pair again.