Reference
Troubleshooting
Fixes for an offline machine, a refused device, a missing agent, lost notifications and other problems, listed by what you see.
Find what you see, then follow the fix. Most fixes use the chaar command on the machine: see Add the chaar command.
A machine shows Offline
chaar's service on that machine isn't running, isn't signed in, or can't get online. First check the machine is on and awake: a sleeping computer can't answer. To keep it awake, see Settings.
If the machine is a Mac with the desktop app, quitting chaar stops its service. Open chaar again, then click its menu bar icon. The first line shows the service's state, as chaard: Off, chaard: Running or chaard: Stopped (chaard is chaar's service).
| The menu shows | What to do |
|---|---|
| chaard: Off | Choose Turn on. |
| Please authenticate | Choose it, and sign this Mac in again in your browser. |
| chaard: Stopped | Read the logs. |
| A line starting with ⚠ | See The menu bar icon shows a mark. |
If the machine is a server or doesn't have the desktop app, use the table below on it.
On the machine, run:
$ chaar service status| It prints | What to do |
|---|---|
chaar service is not installed | Run chaar service enable. |
chaar service is disabled | See why in the logs, then run chaar service disable and chaar service enable. |
chaar needs authentication; run `chaar service login` | Run chaar service login and approve the machine in your browser. |
chaar service is enabled | Check the machine's internet connection, then see Could not reach a relay within 15s and the logs. |
The menu bar icon shows a mark
On a Mac, chaar's menu bar icon is a striped circle. Faded stripes mean the service isn't turned on. A small mark in the corner means something needs you:
| Mark | What it means | What to do |
|---|---|---|
| Three dots | You're signing this Mac in, in your browser. | Finish signing in. |
| A lock | The service is on, but this Mac isn't signed in. | Choose Please authenticate and sign in in your browser. |
| An × | The service is on and signed in, but isn't running. | See A machine shows Offline. |
| An ! | Something went wrong. | Read the line starting with ⚠ in the menu. |
The ⚠ line, such as ⚠ Login failed: …, says what failed and why. It goes away the next time you choose Turn on or Turn off, sign in, or switch Keep Mac awake.
Refused this device
The machine turned your device away. The desktop app shows Connection refused · Retry. The phone shows Refused this device on the machine's card, or the machine's name and refused · Retry at the top of a terminal.
To read why, point at Connection refused · Retry in the desktop app, or read the words after ! couldn't connect: in chaar. The phone doesn't show the reason.
- If the reason says one side
is olderthan the other, see A device says chaar needs updating. - If it says
central authority key is not available yet, the machine's service has just started. Wait a few seconds and try again. - Otherwise, try either of these:
- Ask the machine's owner whether you still have access. See Share with others.
- Sign in again. In a terminal, run
chaar logout, thenchaar login.
A device says chaar needs updating
chaar doesn't update itself. Update all your devices and machines together. When a new version changes how they talk to each other, older ones can't open newer ones until they're updated.
The message says which side is older:
protocol version mismatch: chaard on this machine (v…) is older than this client (v…); upgrade chaar on the machine
protocol version mismatch: this client (v…) is older than chaard on the machine (v…); upgrade this client"chaard" is chaar's service on the machine, and "this client" is the app or command you're using.
- This client is older: update the app or the
chaarcommand you're using. - The machine is older: update chaar on the machine, then restart its service, as Install on your computer or Install on a server shows.
chaar service enableon its own can leave the old version running, so runchaar service disablefirst.
The owner has to sign this machine in again
The desktop app says The owner has to sign this machine in again. The phone says Owner must re-authenticate this machine. The machine isn't set up for this workspace yet. If it was just added, try again in a moment. Otherwise the owner fixes it on the machine:
- If it shows Offline, start with A machine shows Offline.
- Run
chaar service status. If it asks for authentication, runchaar service loginand approve in the browser within 60 seconds. - Otherwise, read the logs for
failed to register key for workspace.
On a Mac with the desktop app, choose Please authenticate in the menu bar instead.
You don’t have access to this machine
You can see the machine, but you can't open its terminals. Ask its owner for Can run. See Share with others.
Can’t reach a machine
| You see | What to do |
|---|---|
| Can’t reach and the machine's name, over a terminal in the desktop app | chaar tries again by itself. Wait, or click Retry now. |
| Can’t load sessions on a machine's card on the phone | Tap Try again. |
| No answer from and the machine's name, at the top of a phone terminal | Tap Retry. |
If it keeps happening, see A machine shows Offline.
My machine doesn't appear after Register machine
Check that you picked the right workspace under Workspace when you registered it. The machine shows only in that workspace.
A link stopped working
| Link | Works for | What to do |
|---|---|---|
The sign-in link chaar login prints | 5 minutes | Run chaar login again. |
The machine's sign-in page, from Turn on or chaar service login | 60 seconds | Start again and finish within 60 seconds. |
| The email that verifies your address | 24 hours | In the console (chaar's website), choose Verify on the banner, then Resend email. |
| A password reset email | 1 hour | Choose Forgot password? again. |
| An invitation | 7 days | Ask to be invited again. See Share with others. |
Your terminal can't find chaar
Choose Install Command Line Tool… in chaar's menu bar, then open a new terminal window.
If it says a chaar command is already installed, it found another one, such as Homebrew's, and left it alone. Keep that one on the same version as the app, or delete it and choose Install Command Line Tool… again.
Could not reach a relay within 15s
chaar couldn't reach its servers, which it needs to connect to a machine. Check the device's internet connection, and that no firewall or proxy blocks chaar: see Network and security.
On a slow connection, give the command longer:
$ CHAAR_CONNECT_TIMEOUT_SECS=60 chaarA Linux machine stopped working after an update
The service keeps running the old version, and stops working if the update moved chaar. Run chaar service disable, then chaar service enable.
Signed out after every restart on Linux
Your desktop has no Secret Service keyring (such as GNOME Keyring or KWallet), so the app forgets your sign-in on restart. Run a keyring that provides the Secret Service, then sign in again.
Keep awake doesn't work on Linux
On Linux, keep awake uses systemd-inhibit, which comes with systemd. The desktop app runs it itself, so check that your Linux uses systemd and has systemd-inhibit installed.
No notifications on your phone
- Allowed? Turn notifications on for chaar in your phone's settings.
- Your own machine? Only machines you set up yourself send notifications, not machines other people share with you.
- Opened chaar lately? A machine stops sending notifications to that phone after 14 days without hearing from it. Open chaar and swipe to each workspace with your machines.
- Machine online? It sends each notification itself.
- On screen already? A notification about the tab you're looking at stays hidden.
- Many at once? A machine sends at most 3 every 30 seconds. Open Needs you to see the rest.
- Logged out? Sign in again and open Home.
Your agent isn't listed
chaar offers Claude Code and opencode. Any other agent runs in a terminal tab: see Work with AI agents.
The machine needs the agent's command installed, and its login shell has to find it:
- Claude Code needs Claude Code's adapter for chat apps,
claude-agent-acp(the olderclaude-code-acpworks too).claudeon its own isn't enough. See claude-agent-acp to install it. - opencode needs
opencode, from opencode.ai.
To check, run this on the machine:
$ $SHELL -ilc 'command -v claude-agent-acp'For opencode, run $SHELL -ilc 'command -v opencode'.
If it doesn't print a path starting with /, set up your shell's startup files so a new login shell finds the command. An alias doesn't count. If your shell takes over 10 seconds to start, make it faster. Then reopen the session on the phone, or quit and reopen the desktop app.
My script's status doesn't show
See Show status from your scripts.
An agent chat stops responding
| You see | What to do |
|---|---|
| Can’t reach the agent | chaar keeps trying. Wait, or press Reconnect now. |
| The agent keeps stopping | Press Restart to try once more. |
| This chat was closed | The chat was deleted, for example on another device. Start a new chat. |
A chat is gone after Quit or a restart
Quitting chaar on a Mac, restarting chaar's service or restarting the machine stops every chat there. The tab stays and shows Ended. Open it once the machine is back, and chaar starts the agent and picks the conversation back up. Ask the agent to carry on.
A chat is gone for good when its tab was closed, after 7 days unused, when the machine's chats pass 1 GiB (oldest go first), or after chaar service uninstall. See Work with AI agents.
Find out why a machine stopped
On the machine, read chaar's logs:
$ chaar service logsAdd -f to keep watching.
If the service won't start at all, run it in your terminal to see why:
Stop the service
Terminal $ chaar service disableRun it here
Terminal $ chaar service runIt prints
error:and the reason if it can't start. Press ctrl-c to stop it.Turn the service back on
Terminal $ chaar service enable
Command line messages
| You see | What to do |
|---|---|
the TUI requires a terminal | Run chaar in an interactive terminal (the TUI is the session browser). In a script, use chaar list --json. |
could not open a browser | Open the printed link on any device, or use chaar login --headless. |
you can only view this machine | Ask the owner for Can run. See Share with others. |
! connection lost · keys are paused | Wait for connected, then type again. Keys typed meanwhile are dropped. |
! couldn't …: can't reach … | Check your internet and that the machine is online, then try again. |
! couldn't load machines · r retry | Press r. If it keeps happening, see A machine shows Offline. |
! couldn't load · press r to retry | Press r. If it keeps happening, see A machine shows Offline. |
! couldn't connect: … or ! disconnected | See Refused this device. |
! no room to split this pane | Make your window bigger, or close a tab. |
! keys.toml line … | Fix that line of your keys.toml, then start chaar again. |
| Dragging doesn't select text | The program uses the mouse. Press ctrl-b[, then v and y. |
✓ copied, but the clipboard is empty | Let programs use the clipboard in your terminal's settings. |
| No notifications | chaar must be running, and your terminal must allow programs to show notifications. |
chaar connect foo made a new session | The name must match exactly, capitals included. Delete the new one with x in chaar. |
Start over on a machine
Delete chaar's data on the machine
Terminal $ chaar service uninstallIt deletes the machine's sign-in and agent chats, without asking. On a Mac with only the desktop app, run:
Terminal $ /Applications/chaar.app/Contents/MacOS/chaar service uninstallRemove the old machine in the console
Remove it from each workspace. See Rename or remove a machine.
Set it up again
Run
chaar service enable, or choose Turn on in the Mac menu bar. See Install on a server.
Remove chaar
Turn off every machine
On each machine, run
chaar service uninstall.Remove the machines from your workspaces
Do this in the console.
Sign out
Run
chaar logout. In the desktop app, choose Log out in Settings › Profile. On the phone, tap the gear on Home, then Log out.Remove the apps
Delete chaar from Applications, and the
chaarthat Install Command Line Tool… added. With Homebrew, runbrew uninstall sixtythreelabs/.tap/ chaar On the phone, delete the app.
Your account stays in the console, and chaar's settings files stay in your home folder.
Stuck? Ask in the Discord community.