Troubleshooting
"tmux not found"
tmux isn't installed or isn't in your PATH.
# macOS
brew install tmux
# Ubuntu/Debian
sudo apt install tmux"cloudflared not found"
Cloudflare's tunnel client isn't installed. This is only required for tunnel mode; --no-tunnel and Daytona direct mode do not need cloudflared.
# macOS
brew install cloudflaredFor Linux, download from cloudflare.com/downloads.
Tunnel won't start
A few things to check (skip this if you're using direct sandbox mode):
- Verify cloudflared works:
cloudflared --version - Make sure you can reach
https://trycloudflare.com - Check if a firewall is blocking outbound connections
Even if the tunnel fails, Termbridge will still work locally - you'll see a local URL you can use on the same network.
"429 Too Many Requests" from trycloudflare
Cloudflare rate limits account-less tunnels. If you see errors like 429 Too Many Requests, try:
- Wait a few minutes and retry
- Make sure no old
cloudflaredprocesses are still running - Use a named tunnel token (recommended for frequent use)
Blank screen or "Unable to load terminals"
This usually means the session expired or something went wrong with auth:
- Check if the local server is still running
- Look at the browser console for 401/403 errors
- Restart Termbridge to get a fresh URL and QR code
No output in the terminal
The tmux session might not be running:
# Check if sessions exist
tmux lsIf sessions show up but the terminal is blank, try:
- Reloading the page
- Checking that your shell supports
TERM=xterm-256color
QR code scans but page is blank
The QR code contains a one-time token. If you've already scanned it once, it won't work again.
Solution: Restart Termbridge to generate a new QR code.
node-pty errors about spawn-helper
Termbridge tries to fix this automatically, but if you see permission errors:
chmod +x node_modules/node-pty/prebuilds/**/spawn-helperStill stuck?
Open an issue at github.com/inline0/termbridge with:
- Your OS and Node.js version
- The error message
- Steps to reproduce