chaarDocsDownloadConsole

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.

Steps for

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 showsWhat to do
chaard: OffChoose Turn on.
Please authenticateChoose it, and sign this Mac in again in your browser.
chaard: StoppedRead 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:

Terminal
$ chaar service status
It printsWhat to do
chaar service is not installedRun chaar service enable.
chaar service is disabledSee 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 enabledCheck 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:

MarkWhat it meansWhat to do
Three dotsYou're signing this Mac in, in your browser.Finish signing in.
A lockThe 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 older than 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, then chaar 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 chaar command 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 enable on its own can leave the old version running, so run chaar service disable first.

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:

  1. If it shows Offline, start with A machine shows Offline.
  2. Run chaar service status. If it asks for authentication, run chaar service login and approve in the browser within 60 seconds.
  3. 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 seeWhat to do
Can’t reach and the machine's name, over a terminal in the desktop appchaar tries again by itself. Wait, or click Retry now.
Can’t load sessions on a machine's card on the phoneTap Try again.
No answer from and the machine's name, at the top of a phone terminalTap 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.

LinkWorks forWhat to do
The sign-in link chaar login prints5 minutesRun chaar login again.
The machine's sign-in page, from Turn on or chaar service login60 secondsStart again and finish within 60 seconds.
The email that verifies your address24 hoursIn the console (chaar's website), choose Verify on the banner, then Resend email.
A password reset email1 hourChoose Forgot password? again.
An invitation7 daysAsk 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:

Terminal
$ CHAAR_CONNECT_TIMEOUT_SECS=60 chaar

A 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 older claude-code-acp works too). claude on 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:

Terminal
$ $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 seeWhat to do
Can’t reach the agentchaar keeps trying. Wait, or press Reconnect now.
The agent keeps stoppingPress Restart to try once more.
This chat was closedThe 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:

Terminal
$ chaar service logs

Add -f to keep watching.

If the service won't start at all, run it in your terminal to see why:

  1. Stop the service

    Terminal
    $ chaar service disable
  2. Run it here

    Terminal
    $ chaar service run

    It prints error: and the reason if it can't start. Press ctrl-c to stop it.

  3. Turn the service back on

    Terminal
    $ chaar service enable

Command line messages

You seeWhat to do
the TUI requires a terminalRun chaar in an interactive terminal (the TUI is the session browser). In a script, use chaar list --json.
could not open a browserOpen the printed link on any device, or use chaar login --headless.
you can only view this machineAsk the owner for Can run. See Share with others.
! connection lost · keys are pausedWait 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 retryPress r. If it keeps happening, see A machine shows Offline.
! couldn't load · press r to retryPress r. If it keeps happening, see A machine shows Offline.
! couldn't connect: … or ! disconnectedSee Refused this device.
! no room to split this paneMake 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 textThe program uses the mouse. Press ctrl-b[, then v and y.
✓ copied, but the clipboard is emptyLet programs use the clipboard in your terminal's settings.
No notificationschaar must be running, and your terminal must allow programs to show notifications.
chaar connect foo made a new sessionThe name must match exactly, capitals included. Delete the new one with x in chaar.

Start over on a machine

  1. Delete chaar's data on the machine

    Terminal
    $ chaar service uninstall

    It 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 uninstall
  2. Remove the old machine in the console

    Remove it from each workspace. See Rename or remove a machine.

  3. Set it up again

    Run chaar service enable, or choose Turn on in the Mac menu bar. See Install on a server.

Remove chaar

  1. Turn off every machine

    On each machine, run chaar service uninstall.

  2. Remove the machines from your workspaces

    Do this in the console.

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

  4. Remove the apps

    Delete chaar from Applications, and the chaar that Install Command Line Tool… added. With Homebrew, run brew 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.

↑↓Move↩Open