Troubleshooting¶
Messages are quoted exactly as roamd shows them. Search this page (Ctrl+F / Cmd+F) for the words you see.
In the browser¶
"Couldn't reach roamd. Check your connection and try again." : Your browser couldn't get through to roamd (you're offline, or the connection dropped halfway). Nothing was changed. Once you're back online, do it again. On the page that approves a new machine, Approve works again after this, and if the machine's details couldn't be loaded at all there is a Try again button.
"Couldn't reach roamd to end your session there. This browser is locked; log out again when you're back online." : You pressed Log out with no connection. This browser is locked and has forgotten your vault key, but roamd's server wasn't told, so your session there is still open. Log out again when you're online to end it.
"roamd couldn't check your organisation's rules just now. Try again in a moment." : Your organisation has rules about computers or sharing, and roamd couldn't read them, so it holds things back rather than guess. Wait a moment and try again.
"Your access to this machine has ended." : You were given access to a computer for a limited time, or the owner removed you, and a command or terminal you had open was stopped. Ask the owner to let you in again.
"a guest who can only watch reaches only the folder files are sent to" : You were shared a computer to watch only, with files allowed. You can list and fetch what is in the folder files are sent to, and nothing else on the computer.
"Wrong email or master password." : Check both for typos (the password is case-sensitive). If you've forgotten it, use Forgot password with your recovery key.
"Could not connect to …" right after opening lots of terminals at once : roamd limits how fast one account can open terminals, and how many can be waiting for one computer at the same time (guests get a smaller share of those places, so they can never leave the owner without one). Wait a minute and open them again, a few at a time.
"Too many tries. Wait a minute and try again." : To stop password guessing, roamd only allows a few tries a minute. Wait a minute.
"That address has been sent several emails already. Try again later." : Sign-up codes and invitations to one address are capped, so nobody can flood an inbox. Wait a while, then try again. If you're the one waiting for the email, check the spam folder and the earlier ones first.
No code in the email after creating an account; it says the address already has one : You (or someone) already made an account with that address. Choose Log in; if you've forgotten the password, use Forgot password with your recovery key. If you never made one, someone else tried with your address: nothing changed, ignore it.
"That sign-up waited too long. Please fill in the form again." : The code wasn't entered in time, or had too many wrong tries. Fill in the form again for a new code.
"Check your authenticator app" after typing the right password : You chose an authenticator app as your second step. Type the 6-digit code your app shows for roamd now. Lost the phone? Use Forgot password with your recovery key.
"On a browser new to this account, log in with your master password first; then you'll use your passkey." : Your second step is a passkey, so a new browser needs your password and then the passkey. Log in with your password; your browser then asks for the passkey.
"That's your last passkey, and a passkey is your second step. Choose another second step first." : You tried to remove your only passkey while new browsers need one. Change the second step to an emailed code (or an authenticator app) first, then remove it.
"Could not start the change." / "Could not check the code." / "Could not save the change." / "Your passkey was refused." : Changing the second step didn't go through (the connection dropped, or what you entered wasn't accepted). If roamd's server gave a reason, it is shown instead. Start the change again.
"Add a passkey first (above), then choose it here." : To use a passkey as your second step, add one under Passkeys first.
"That took too long. Please start again." / "That reset waited too long. Please start again." : The change or the reset waited too long for its code. Start it again.
"Update roamd on … to share it." : That computer's roamd is older than sharing. Reinstall roamd there (same command as when you added it), then try again.
"… is offline. Try again when it's online." (sharing) : Letting someone in happens through your own connection to the computer, so it must be online with roamd running.
"Too many invites. Wait a minute and try again." : Too many invitations were sent in a short time. Wait a minute.
"Could not share: …" : roamd's server refused the invitation and the rest says why, for example "that's your own address" (you can't share with yourself) or "that isn't a time a share can last" (choose one of the listed times). Fix it and share again.
"Could not remove …: …" / "Could not leave …: …" / "Could not stop sharing: …" / "Could not accept …: …" / "Could not decline …: …" / "Could not approve: …" : roamd's server couldn't do it, and the rest says why (often the connection dropped, or the thing had already changed). Try again; if it keeps happening, reload the page.
The sharing codes don't match : Don't let them in: click Cancel. Something between you may be interfering.
"That address already has access. Stop sharing first, then share again with the new limits." : That person is already invited or let in, with different limits. Click Stop sharing next to them, then share again.
"You can watch these sessions, not type in them." / "Nothing is running on this machine to watch." : You're a watch-only guest. You can look at sessions that are running; you can't start one or type. Ask the owner if you need more.
"a watch-only guest can only look at a session" / "Your access to this machine has ended." : You asked for something a watch-only guest can't do, or your time ran out. The owner can share again with different limits.
"You can join only the sessions shared with you." / "None of the sessions shared with you is running now." / "you can only join the sessions shared with you" : The owner shared only some of their sessions with you. You can join those (typing only in the ones they let you type in), but not start one or open a plain shell. If one you had is missing, the owner may have ended or renamed it. Ask them to share it again.
"you can only end the sessions shared with you, and rename none" : You were shared only some sessions: you may end those (if the owner allowed it), never rename them, and nothing else.
"Update roamd on … to share only some of its sessions." : That computer's roamd is older than picking sessions. Update it (the update offer when you connect, or the install command again), then let them in again.
"… can't be asked which sessions are running. Check it's online, then choose again." / "No sessions are running on …. Start one, then choose again." / "Pick at least one session to share." (Share box) : Picking sessions needs the computer online and at least one tmux session running there. Choose All sessions and back to Only the sessions I pick to ask again.
"Couldn't reach … Press Reconnect to try again." (after being disconnected) : The owner pressed Disconnect now. You're kept out for a few minutes; try Reconnect after that.
"… was disconnected from …" / "… wasn't connected." / "Could not disconnect: …" (owner) : The result of Disconnect now. Nobody is removed: Stop sharing is what ends a share.
"Choose a whole number between 1 minute and 365 days." : The amount typed under Another amount… isn't a whole number in that range. Fix it, or pick one of the usual times.
"…'s time has ended." (owner) : You tried to change a guest whose time is over. Click Stop sharing to clear them.
No list of sessions when I click Connect
: The computer doesn't have tmux, so you get a plain shell. Install tmux there to keep
sessions running after you leave (see Usage). On Windows that means psmux
(winget install psmux); restart roamd or sign out and in if it was installed after roamd started.
I can't see my list of machines while connected : The machines are always in the left-hand menu (on a phone, the menu icon at the top left). Choose Disconnect in a computer's ⋯ menu to end its connection.
The last lines of the terminal are hidden behind the buttons : The terminal resizes itself to fit above the key row and voice buttons, including when voice messages appear there. If the bottom is still hidden, reload the page: your session on the computer keeps running.
Where did "Add a machine" go? : The install instructions open as a pop-up from the Add a machine button at the top right of Open sessions. Close or Escape puts it away.
My tmux sessions didn't come back after a restart
: Check Bring sessions back after a restart is ticked in the session list (or run
roamd tmux-restore status on the computer). roamd has to start with the computer:
run roamd service install there (on a Linux server, also the extra command it
suggests). Sessions are saved every few minutes, so very recent changes can be
missed. If you run more than one tmux server, the add-on doesn't restore by itself.
On Windows it also needs PowerShell 7 (pwsh), and sessions come back when you log in
again, within a minute or so; an AI tool started through node (an npm install) is
shown to psmux as node, so it isn't resumed, only its folder comes back.
"returned 127" mentioning continuum_save.sh, instead of my session
: tmux, which keeps your session running, is showing an error from its session-saving
add-on. A background helper tried to run a save command that was no longer there.
Your AI app can still be running underneath. While this error screen is visible,
press Ctrl+C once to dismiss it. If it keeps returning, ask the machine's owner
to check the background helpers and the add-on's folder. Don't stop tmux: doing so
would end the running sessions.
```text
Save command missing -> tmux shows an error
|
Ctrl+C dismisses it
|
Running session returns
```
A program ran again after a restart and I didn't want it to : Each pane's program starts again as it was typed. Close that pane (or session) before restarting if its program mustn't run twice.
"Only the machine's owner can change this." : Bringing sessions back is the owner's choice for their computer. Ask them.
"Couldn't change it: …" (bringing sessions back) : The computer couldn't change the setting and the rest says why, for example it couldn't download the add-ons or write its tmux config. Check the computer's internet connection and try again.
"This machine's own tmux config sets up tmux-resurrect or tmux-continuum…" : You set these add-ons up yourself, so roamd doesn't change anything. Adjust them in your own tmux config.
"Choose another name: …"
: tmux session names can't be empty, very long, or contain : or ..
"That login waited too long. Please log in again." : The code from the email wasn't typed in time. Log in again for a new one.
"Your master password is wrong." (removing a passkey) : Removing a passkey needs your master password too. Retype it.
"Check your email" after typing the right password : This browser is new to your account, so roamd emailed you a 6-digit code. Type it in to finish logging in; the browser is remembered after that. If an email like this arrives when you weren't logging in, someone knows your master password: change it now.
"That passkey isn't set up for roamd. Log in with your master password." : The passkey you picked isn't one added to a roamd account, or it was removed on the Account page. Log in with your password, then add it again under Account → Passkeys.
"The passkey request was cancelled or timed out." : The Face ID, fingerprint or PIN request was closed, or not answered in time. Click the button again.
"that passkey request has expired; try again" : Too long passed between clicking and answering. Click the button again.
"Check your email" after using a passkey : This browser is new to your account, so as with your password we also need the code we emailed you. The email names the passkey used. If it arrives when you weren't logging in, someone has that passkey: remove it (Account → Passkeys) and change your master password.
"This passkey can't unlock your vault, so roamd can't use it. Most phones, laptops and newer security keys can: try one of those." : This passkey can't make the secret roamd needs to unlock your vault. Use a different passkey: your phone or laptop's built-in one usually works.
"that passkey login has expired; start again" : Too long passed before the emailed code was entered. Click Log in with passkey again.
"Your master password is wrong." when adding a passkey : Adding a passkey needs your current master password. Check it for typos.
"That passkey is already set up for this account." or "That passkey is already set up for a roamd account." : This passkey is already in use. You don't need to add it again. It's listed under Account → Passkeys (the second message means it's on another roamd account).
"This browser can't use passkeys." : The browser has no passkey support. Use your master password, or a recent Chrome, Edge, Safari or Firefox.
An email says "A passkey was added to your roamd account" and it wasn't you : Someone got in with your master password. Log in, remove that passkey (Account → Passkeys), change your master password and replace your browser key.
"The two passwords are different." / "The two new passwords are different." : The password and its repeat don't match (creating an account, resetting, or changing the password). Type both again.
"Your master password is wrong." / "Your current master password is wrong." (new recovery key, or changing the password) : These actions ask for your current master password again. Retype it and check for typos.
"That recovery key has a typo. Check each group of four." : The key has a built-in check that catches most typos. Capitals, spaces and dashes don't matter; the letters and digits do.
"Wrong email or recovery key." : The key is typed correctly but belongs to a different account, or the email is wrong.
No email with a code arrived : Check your spam folder for an email from roamd with a 6-digit code. Still nothing? Choose Email me a new code (only the newest code works).
"… didn't reveal the secret it promised, so there is no pairing code to show. On …, type n: someone may be interfering."
: While approving a computer, the answer from the computer wasn't what it had promised.
Type n on the computer. Then run roamd login there again; if it keeps happening,
something between you and the computer is interfering.
"… didn't answer in time. Run roamd login there again for a new code."
: The computer stopped waiting (or roamd login was closed) before it finished pairing.
Run roamd login again.
"That code isn't right. Check the latest email from roamd." : A typo, or an older code. Only the newest email's code works.
"That code has expired or had too many wrong tries. Email yourself a new one." : Codes only work for a short time and allow a few tries. Choose Email me a new code.
"Too many codes asked for. Wait a minute and try again." : Wait a minute, then ask again.
"Signed out Chrome on Android. It needs an emailed code to log in again." : You signed that browser out from Account → My browsers. It can log in again, but only with your master password and a code we email you. If you lost a phone, also change your master password and replace your browser key.
"That isn't a roamd vault file."
: The file you chose to import isn't a vault export. Choose the roamd-vault-….json file
you saved from Account → Vault backup.
"That file can't be opened with your vault: it was changed, or it is from another account. Nothing was restored." : Import checks every item first. The file was edited or damaged, or it was saved from a different account's vault. Nothing in your vault changed.
"A new recovery key takes over on …. Until then your current recovery key works." : You made a new recovery key and it is waiting on purpose. Your current key works until it takes over, and for a while after. Wasn't you? Use your current recovery key (login page, Forgot password): that cancels the new one. Or press Cancel the new key in Account → Recovery key.
An email: "A new recovery key was made for your roamd account" : A new key was made, with your master password. If that was you, save it and do nothing. If not, someone knows your password: use your current recovery key to cancel it and set a new password, then look at Activity.
My passkeys are gone after I used my recovery key : That's on purpose. Using the recovery key removes every passkey, so one a thief added can't stay. Log in, then add your passkeys again on Account. The "password was reset" email says when it happened.
An email: "Your roamd password was changed" or "Your roamd password was reset" : Your password changed, or was reset with your recovery key. If that was you, ignore the email. If not, someone knows your password: on the login page choose Forgot password and use your recovery key to set a new one, then look at Activity.
"Too many wrong codes, so codes are paused until tomorrow. …" : Someone (maybe you) typed too many wrong codes today. Codes only come after the right password, so if it wasn't you, change your master password as soon as you can. We also email you when this happens. Try again tomorrow.
"Approved, but its identity could not be saved to your vault: …"
: The computer was approved, but your browser couldn't save its identity, so it won't connect
from this browser until that is saved (see the next entry). Check your connection, then
run roamd login on the computer again.
"roamd has no saved identity for …, so it won't connect…"
: Your vault has no record of this computer's ID (the one you checked with the 6-digit
code), so your browser can't tell it from an impostor. On that computer, run
roamd login again to approve it.
"The settings saved on roamd's server are older than this browser expected, so roamd stopped." : First refresh the web app: an earlier version could mistake a delayed response during a settings save for older server data. The current version fetches again when a newer save overtook the response, without showing this warning. If it remains, your browser has seen a newer copy of your saved settings than the server just gave it, so it stopped instead of quietly using older ones. This is usually harmless: it happens when the server was restored from a backup or reset. Choose Use the server's copy and confirm. You may then need to sign in again. Anything you changed after that copy was saved may be missing, and a key or setting you had removed could come back, so check your approved keys. If it keeps happening and the server wasn't restored, don't sign in on it.
"roamd's server asked for weaker password protection than roamd uses…" : Your browser refused to log in, so your password wasn't exposed. Try again later; if it keeps happening, the server can't be trusted.
roamd run says "connecting to …" and nothing else
: That is normal if the next line is roamd: connected. This machine is online; leave this
running (Ctrl+C stops it). roamd run stays in the foreground, so you don't get your
prompt back. If it never says connected, it says the hub didn't answer the connection;
trying again after a while and keeps retrying: check that this computer can reach the
internet and the address it was set up with. Setting up with roamd login runs roamd in
the background for you, so you rarely need roamd run by hand.
The Connect button is greyed out / the computer says "offline"
: roamd isn't running on that computer. Run roamd run there, or set it to start by itself
with roamd service install. The card says since when and why it may be:
**"offline since 14:02 · roamd was stopped there"**
: roamd said goodbye: it was stopped, or the computer was shut down normally. Start it
again.
**"offline since 14:02 · the machine may be asleep or off, or have lost its internet"**
: The connection ended without a goodbye. Switch it on, make sure it isn't asleep, or check its network.
A computer that lost its internet this way is shown offline after a short while, once
it stops answering; before that it may still look online for a moment.
**"offline: roamd isn’t running there"**
: That computer has never connected. Run `roamd run` there.
The Snippets window shows no commands for my AI app. : While it says Loading…, give it a few seconds. They appear a few seconds after the app starts, once your computer has noticed it, and only while the session you're looking at is running one of the apps roamd knows (Claude Code, Codex, Gemini CLI, aider, opencode, Copilot CLI). An app started some other way, or on a computer running an older roamd, isn't noticed: update that computer. Anything you hid is brought back with Restore (named after the app), beside the tabs on the app's tab. If a command you expect is missing or an old one is still there, the lists are refreshed from the app's own documentation once a week, so a brand-new command can take a few days to show.
"A snippet needs a name and a command." : Fill in both boxes before saving.
A snippet has Insert but no Run
: It looks risky (for example it contains rm or sudo), so it is only typed, never run.
Press Enter yourself after reading it.
"Could not save that: …" (renaming or grouping a computer) : Your browser couldn't save the change to your account, usually because the connection dropped. Try again. Your names, groups and order are stored encrypted, so they follow you to every browser once saved.
"roamd … is out of date" : That computer runs an older roamd than the current release. Connect and accept the update offer, or install the new version there.
"Warning: … is not presenting the identity you approved…"
: Your browser noticed that the computer you're connecting to isn't the one you approved.
Don't continue. If you reinstalled roamd there yourself, remove the computer in
Open sessions and run roamd login on it again. Otherwise, someone may be trying to
impersonate it.
"this key is no longer approved here"
: You asked a computer for something (a file, a session change, a key switch) with a browser
key it no longer accepts, for example because it was revoked with roamd keys revoke
while the terminal was open. Run roamd login on the computer to approve this browser
again.
"Login failed: … rejected the username, password or key."
: The computer doesn't accept this browser. Maybe the browser key was revoked with
roamd keys revoke. Run roamd login on the computer to approve it again.
"The code … is unknown or has expired. Run roamd login again for a new one."
: Approval links are short-lived. Run roamd login again.
"old key until online" next to a computer in Open sessions : You replaced your browser key and that computer hasn't switched yet because it's offline. Start roamd there; it switches while a roamd page is open.
"update roamd here to use your new key" next to a computer
: Its roamd is too old to switch keys. Update it (see Installation) and
restart it (roamd service install again, or stop and start roamd run). roamd asks it
again as soon as it reconnects, while a roamd page is open.
"Update roamd on …: it still trusts only the old key until then." : After Replace browser key, that computer's roamd was too old to switch. Install the latest roamd there (see Installation) and restart it; it switches next time it's online with roamd open in your browser.
"roamd on … is out of date, so it still trusts only your old browser key. Update roamd there to finish replacing the key." : Same cause, shown when you connect. You're connected with the old key for now.
"Couldn't reach … yet; roamd will keep trying." : The computer is listed as online but didn't answer the switch. Leave a roamd page open; it tries again every minute or so.
Voice is on but I only see the messages, I don't hear them : Your browser has no voice that runs on the device, and roamd won't use online voices (they would send your terminal's text away). When you turn Voice on you'll see "This browser has no voice that runs on this device, so messages are shown here instead." Try another browser, or add a voice in your system's speech settings.
Dictate opened a note called "Dictate runs in your browser" and didn't listen : That's the one-off first-use note. Nothing listens until you press OK; then it starts listening, and the note doesn't come back. If you close it without OK, Dictate stays off and the note shows again next time.
Dictate or Hands-free says "Getting speech ready…" : Your browser is downloading the speech model, a one-off the first time on this browser (a line under the terminal shows how far it has got). It waits until the model is ready before it starts listening. If it never finishes, check the connection to our website, and that the browser has room to keep it: private windows and cleared site data make it download again.
Dictate says "I didn't hear anything. Tap Dictate and talk after the beep." : You tapped Dictate a second time before saying anything loud enough to hear. Tap Dictate, wait for the beep, talk, then tap Dictate again to finish. It doesn't stop by itself when you pause.
Dictate says "I didn't catch that. Tap Dictate to try again." : Your voice was recorded but no words came out of it (too quiet, too short, or only background noise). Tap Dictate and try again, a little closer to the microphone.
"Hands-free needs the microphone: allow it for this site, then try again." : The browser blocked the microphone, so Hands-free switched itself off. Allow the microphone for this site in the browser's site settings, then tap Hands-free again.
Hands-free keeps saying "I didn't catch that" : It heard nothing loud enough. Check the browser is using your headset's microphone and that the site may use the microphone. Speak after the first beep.
In a noisy place, Hands-free's bar never drains and it doesn't take what I said : The room is so loud, or the noise so changeable (music, a café), that it can't tell when you've stopped. It settles on the new background after a few seconds of the noise staying about the same. Move somewhere quieter, or speak closer to the microphone.
Hands-free hears the wrong words : The speech model is small, so it's best with common commands. Words you add under Voice on the Account page help it. If a command is misheard, say "cancel": nothing runs until you say "run it".
The headset button does nothing : Not every phone and browser passes headset buttons to web pages. Tap Hands-free instead; it does the same. Keep the page open (it keeps the screen awake).
Ctrl + Alt (or Ctrl + Shift) doesn't start listening on my computer : Hands-free must be on first (the button shows as pressed) and a terminal must be open: the shortcut works like a headset button and does nothing while it's off. Press the two keys together and let go without touching anything else (a third key, or AltGr, spoils it). Check Account → Hands-free shortcut hasn't been set to None or to the other pair, and that this page is the one in front. On a phone or tablet the shortcut isn't used: press the headset button or tap Hands-free.
Words in the Compose box change while I'm dictating : That's expected. The words of the phrase you're still saying are a first guess, shown so you can see it working. When you pause, that phrase is worked out properly and the guess is replaced. Nothing is sent to the terminal until you press Send.
Dictate shows "Working it out…" for a long time : Your browser is turning your voice into words, which takes a few seconds on a phone and longer on an old one. A long sentence takes longer: keep commands short.
"Dictate stopped: …" or "Hands-free stopped: …" and the reason is about the speech model : roamd checks the speech model before it uses it, and refused it. The reason says why: the list of models isn't signed by roamd, the list is older than one this browser already used (an old list is refused even though it was once signed), the list is unreadable or doesn't name the model, or the downloaded file isn't the one roamd signed. Nothing is used or kept. If it happens on every try, the download site may be serving a broken copy: tell whoever runs it. See the messages table below.
"Couldn't reach roamd to get the speech model, and none is saved on this device yet." : This browser has never downloaded the model and can't reach our website now. Connect, then try again. After one successful download it works without a connection.
"Dictate needs the microphone: allow it for this site, then tap Dictate again." : The browser or phone refused microphone access. roamd now asks as soon as you tap Dictate (or OK on its first-use note), before loading speech. Allow the permission prompt. If no prompt appears, microphone access may already be blocked in your browser or phone settings. Installed apps have no address bar: open the site in your browser to check its microphone settings, and check your phone's microphone permission for the browser or installed app. Reopen the installed app and try again. The permission prompt in installed phone apps still needs checking on real devices. After a completed recording, roamd now keeps microphone access muted while the app stays open, so tapping Dictate again does not ask for a new stream. Leaving the app releases it; the browser may ask again when you return. Cancelled starts and errors also release it.
```text
Tap Dictate -> allow microphone -> load speech -> beep -> talk
| |
first-use OK refused/no prompt -> check permissions -> retry
```
"
"The update failed: the installer didn't finish on the machine"
: The installer couldn't run there (no curl or wget, no internet, or a Windows
computer). Nothing was changed. On that computer, run the install command from Add a
machine, then roamd service install.
"The update failed: the update isn't signed by roamd" : The computer checked the new roamd's seal and it didn't match roamd's key. Nothing was changed. This is the check doing its job; if it keeps happening, tell us.
"The update failed: the download doesn't match what was signed" : The file the computer downloaded isn't the one that was sealed (damaged, or swapped on the way). Nothing was changed. Try again later.
"The update failed: couldn't download the update: …" : The computer couldn't reach our website. Check its internet connection, then try again.
"The update failed: already up to date" : The computer already runs the newest roamd.
"The update failed: an update is already being installed" / "The update failed: an update is already waiting to take effect" : An update was already started, or was installed and is waiting for roamd there to restart and prove itself. Wait a little, then connect again; nothing was changed by this try.
"The update failed: only an owner's key can update roamd" : You were given this computer by someone else (a guest). Ask its owner to update it.
"The update failed: couldn't install the update: …" : The computer couldn't write the new file where roamd lives (often a folder only an administrator can change). Install by hand, as the same user that installed it.
"The update failed: the new version wouldn't start, so the old one was kept" : The computer downloaded and checked the new roamd, but it wouldn't run there, so it wasn't installed. Nothing was changed. Tell us which computer and system it is.
"roamd: this new version couldn't start; trying again, and if it still can't the old one comes back." (in its messages) : You updated, and the new roamd couldn't start at all. It tries once more, and if it still can't, the computer goes back to the roamd it had before. Nothing for you to do.
"roamd: the new version didn't stay up, so the old one is back" (in its messages) : The computer went back to the roamd it had before, on its own, because the new one kept stopping. Update again later; if it keeps happening, tell us.
"Could not replace the key: …" (Replace browser key) : Your browser couldn't finish replacing its key; the rest says why (usually the connection). Try again.
"Could not save the locking setting: …" / "Could not save the voice settings: …" / "Could not save the voice setting: …" / "Could not save the setting: …" : Your vault couldn't be saved, usually because the connection dropped. Check it and try again.
"Could not save the update setting: …" / "Could not check for a roamd update: …" : Your vault couldn't be saved, or the page couldn't read the newest release. Reload, and try again.
I updated, and now the computer is offline
: If you started roamd run by hand, it stops after an update; start it again. As a
service it restarts by itself within a few seconds.
The page asked for my password again : That's the lock: after closing the tab, or after the time without use you chose in Account → Locking. Set it to Never to stop it locking while the tab is open.
"You're offline. Reconnect to reach your machines." : Your device has no connection. roamd opened from the copy kept on your device, but it can't reach us or your computers. The message goes away by itself once you're back online.
A blue refresh button at the far right of the top bar : A newer roamd page has downloaded. Press it when it suits you, or just reload the page any way you like: either way the new version loads. Nothing changes until then. Reloading closes an open terminal, but its tmux session keeps running on the computer: just rejoin it. The button also shows above an open terminal on a phone.
```
new version downloaded --> refresh button turns once at the top right
|
press it, or reload the page some other way
|
v
the new version loads
```
"This browser can't install roamd. Chrome, Edge, Brave and Safari can." : Your browser doesn't offer installing websites as apps (Firefox on a computer, for example). Use one of the browsers named to install it; roamd works the same in a tab.
No Install bar on my phone : On an iPhone or iPad only Safari can add roamd: tap Share, choose Add to Home Screen, then tap Add. On Android use Chrome. If you chose Not now, use Account → Install roamd on this device. Once roamd is installed, the bar no longer appears.
Apple keyboard dictation repeats the first letters or word
: A captured iPhone dictation inserted th, then appended this, leaving ththis
inside the browser's own input field before roamd sent it. The terminal input was
zero-sized, fully transparent and far outside the visible screen. It now has a
stable editing area inside the terminal; only its text is hidden, so the terminal
still draws the words normally. Long text wraps within that area. This corrects
the input layout used by the phone keyboard, but still needs a real-device retry
to establish whether it fixes the dictation duplication. No repeated-word filter
is applied, so intentional repetition is kept.
Repetition has still been reported on a physical Apple device, so this remains an
open bug despite passing browser event tests. To help diagnose it, open Account >
Input diagnostics, turn on Record input events, return to the terminal and
reproduce it once. Return to Account and tap Copy report, then paste that report
into your support conversation. This stops recording. The report contains event
timing, the actual text supplied by your keyboard, text sent to the terminal, cursor
positions and browser/build information. It includes your typed or dictated words
while recording is on, but does not record audio or remote terminal output. Nothing is uploaded automatically; the bounded report
stays in memory until you clear it or reload. Starting a recording clears the old one. For a draft you can review before sending, use Compose.
```
Apple keyboard -> on-screen editing area -> changed text
correction -> edit affected words -> keep sentence tail
record events -> reproduce -> copy report -> share with support
```
Phone keyboard dictation suddenly repeats a long block of text : Reload roamd to get the corrected input handling. Earlier versions could send the same keyboard updates more than once or resend text left in the hidden input box. For a long prompt, open Compose (under More on a phone), use your keyboard's microphone there, review the words, then tap Send. This keeps the draft editable before it reaches the terminal.
```
keyboard microphone -> Compose -> review -> Send -> terminal
```
Command-V does nothing in Safari, but Edit → Paste works : Reload roamd to get the corrected keyboard handling, click inside the terminal, then press Command-V again. Until you reload, use Edit → Paste in the Mac's top menu bar. Right-click may open tmux's menu instead of Safari's menu.
"Allow clipboard access for this site, then tap Paste again." : Your browser asked to let roamd read the clipboard and it was refused (or not answered). Allow it in the site settings, then tap Paste again.
"Press and hold a line in the terminal to select it, then tap Copy." : Nothing was selected. Press and hold a line of the terminal until it highlights (drag to take more lines), then tap Copy. "Copied." means it's on your clipboard.
"Couldn't copy: allow clipboard access for this site." : The browser refused to let roamd write to the clipboard (from the terminal's Copy, or from the copy button next to a saved file's path). Allow it in the site settings.
"Couldn't copy: select the key and copy it yourself." : The browser wouldn't let roamd use the clipboard for the recovery key. Select the key on the page and copy it yourself, then store it somewhere safe.
The key row doesn't show on my phone (or shows on my computer) : Account → Terminal keys → Show the on-screen key row: Automatically shows it on touch screens only; choose Always or Never for this device.
"You have … terminals open, the most this plan allows. Close one to open another." : Your plan limits how many terminals can be open together. Close a tab (its tmux session keeps running) and open the one you want.
"Your plan ended. Renew to open more than 2." : Your paid plan ended while more than 2 terminals were open, so the ones you used least recently were closed. Nothing running is lost: the tmux session is still on the computer. Renew on Plans, or close a tab and open the session again.
"Free accounts can open 2 terminals at once…" : You already have 2 open. Close one (its tmux session keeps running), or choose the paid plan on Plans.
"Free accounts can use 2 machines…" : A free account can use 2 machines. You tried to pair a third, or your plan ended and this machine is past the first 2 you paired. Remove a machine you no longer use, or choose the paid plan on Plans. Nothing is deleted when a plan ends: renew and it opens again.
I paid but Plans still shows Free : The page checks for Stripe's confirmation. If it takes longer than usual, the page says so and keeps checking while it is open. Some payment methods, such as bank debits, take days to clear: the plan starts when the money arrives. Stripe's email receipt is sent once it has.
"A payment you started is still being confirmed. Try again in a minute." : You already paid on a payment page that roamd hasn't heard back about yet. This stops you paying twice. Wait a minute and look at Plans again.
A tab didn't come back after a reload : Tabs come back only for tmux sessions, and only if the session is still running on the computer. A plain shell, or a session that ended, is left out on purpose. Open it again from Open sessions. Tabs that do come back reconnect together, so a page with several open is ready as soon as the slowest one, not after each in turn.
"Connect to a machine first." : Files go to the terminal you are looking at. Open one from Open sessions, then try again.
"… is larger than the most roamd will send (… MB)." / "… is larger than the most roamd will fetch (… MB)." : There's a limit on each file. Split or compress it, or use another way for something that big.
"that file is larger than this machine will accept" : The computer you are sending to has a limit of its own, and the file is over it. Split or compress it.
"The owner of … hasn't allowed file transfer for you." : You're a guest on this computer, and its owner hasn't turned files on for you. Ask them to tick Can send and fetch files next to your name in Sharing.
"Update roamd on … to send and fetch files." : That computer's roamd is older than files. Update it (see Updating roamd on a computer).
"Waiting to reconnect to …" / "Lost the connection to …." : The connection dropped in the middle of a transfer. If the terminal rejoins in a minute or so the transfer carries on by itself; if not, send it again and it continues from what the computer already has.
"… isn't a folder on this machine" / "give the folder's full path, or one starting with ~"
: A typed path needs to be the full path of a folder that already exists, or one starting
with ~ for your home folder. A typed file opens like one picked from the list.
"couldn't save to …: permission denied" / "…: the disk is full" : The computer couldn't write there. Pick another folder or free some space.
"that upload is still being received here; try again in a moment" : An earlier try at the same file hadn't let go yet. Wait a moment and send it again.
"no such folder or file" / "… isn't a file" / "give the file's full path, or one starting with ~/"
: The file or folder isn't there (someone may have moved it: tap refresh), or the path you
typed isn't a full path. Give the whole path, or one starting with ~/ for your home folder.
"too many files with that name" : The folder already holds many files with the name you sent. Rename the file or choose another folder.
"Nothing here matches that." / "Nothing in this folder." : The folder you're looking at has no name containing what you typed in Filter by name (clear the box to see everything), or it's empty. The filter looks through the whole folder, not only the part shown.
A big folder doesn't show everything at once : A big folder comes a part at a time: scroll down and the rest is fetched. Or type part of the name in Filter by name, which looks through the whole folder.
"… already exists" : A new folder or a rename can't take a name something in that folder already has. Choose another name.
"that isn't a plain name (one name, no slashes)"
: A name can't hold / or \, be . or .., start or end with a space, or hold hidden
characters. On Windows, < > : " | ? * aren't allowed either.
"couldn't move it to the Bin: …" : The computer's Bin couldn't take it. On Linux this happens for a drive with no Trash of its own; on a Mac, for something on another drive than your home folder. Nothing was deleted. Delete it in a terminal if you really mean to.
"that folder can't be deleted from here" : Your home folder and the top of the disk can't be deleted from the files panel.
"a guest who can only watch can't change files" : You can look at and fetch files in the shared folder, but not rename or delete them.
"that is too big to fetch at once" : What you chose to download as a zip is over the limit. Choose fewer files, or fetch big files one at a time.
No preview, only "There is no preview for this kind of file." : PDFs, documents, archives and programs aren't previewed: download them to open them. Very big pictures and videos aren't fetched just for a preview either.
"unknown request" when showing a folder : That computer's roamd is older than the folder browser. Update it (see Updating roamd on a computer).
"Couldn't read the record of … (offline, or running an older roamd)." : Activity asks each computer for its own record when you open the page. That one was off, or its roamd is older than the activity record. Turn it on or update it, then open the page again.
"Couldn't load your account's activity." : The page couldn't get your account's own events (the connection dropped, or roamd's server had a problem). Open Activity again. Each computer's own record is asked for separately, so those can still appear.
An entry says "A key (SHA256:…) …" : Something connected or tried to with a key that isn't one of your browsers or guests (for example a key you have since removed). If you don't recognise it and it says it was refused, nothing got in.
"Someone tried to sign in with the wrong master password." : The wrong password was entered for your address. If it was you, ignore it. If it wasn't, a password you haven't shared can't be guessed from here, but change it if you're worried.
"Nothing to show for this choice." : The Where and What choices together match nothing. Set them back to everything.
"Not connected" : No terminal is open in this tab (it never connected, or it was disconnected). Open one from Open sessions.
An amber "reconnecting" mark on a tab : The connection dropped (a sleeping phone, a changed network, a restarted computer) and roamd is rejoining your tmux session. While it does, the tab shows an amber line along its bottom edge that sweeps across every few seconds. A grey line means the session is still joining for the first time. Nothing to do; Disconnect stops it.
"Couldn't reach …. Press Reconnect to try again." : The computer stayed unreachable. Check it's on and roamd is running there, then press Reconnect. If it was only restarting (after an update, say), you don't need to: the terminal reconnects by itself as soon as the computer is back.
"A plain shell can't be rejoined: it ended with the connection. Press Reconnect to start a new one." : A plain shell ends when its connection does. Press Reconnect to start a new one, and use a tmux session next time to keep your work.
"The tmux session "…" is no longer running on …. Press Reconnect to choose another." : The session ended while you were away (the computer restarted, or it was closed there). Press Reconnect and pick or start a session.
A computer shows no "waiting for you", "working" or "idle" counts : It says nothing when it has nothing to say that your browser can trust. Check that the computer is online, has tmux, has a session running, and runs a current roamd (an older one doesn't report). The first report takes a few seconds. Until then, and while the computer is offline, its sessions show a faint grey ring. Once it has reported, what it said stays until it says otherwise: your browser never times it out. Computers shared with you never show it.
"no sessions" : The computer's tmux is running but has no sessions. Start one from Connect.
Connect opens a plain shell and never asks which session : The page asks the computer for its tmux sessions and shows the list (even an empty one, so you can start a session) whenever tmux is installed. A computer whose tmux is only on the PATH of a login shell, such as a Mac with Homebrew, used to look as if it had no tmux. Update roamd on that computer, and Connect shows the list again. If tmux really isn't installed, there is nothing to list.
A computer's sessions are missing from the column on the left (but Connect lists them) : The column shows what the computer itself reports. A Mac's roamd runs in the background without Homebrew's folders, so a roamd from before 0.2.10 could not find tmux to report on it, though Connect (which uses a login shell) could. Update roamd on the Mac. Until then the column shows Choose a session… for it, which opens the same list as Connect.
Selecting text in tmux doesn't copy it : Update the page (it needs this release), then check Account → Copying → Copy what I select in the terminal is ticked. With tmux's mouse mode on, hold Shift to select the plain way. If your browser says Couldn't copy, tap Copy, or allow clipboard access for this site.
"Update roamd on this machine to rename or end sessions." : That computer runs a roamd from before renaming and ending sessions. Update roamd there (Connect offers it), then try again.
"Choose another name: …" / "Couldn't rename … : …"
: tmux doesn't allow : or . in a session name, and a name can't be empty or very long.
If the name is taken, tmux says so ("duplicate session"): choose another.
"Ending …" / "Ended …." : Shown just under the session list while the machine ends a session, then once it has. If neither appears, scroll up to the list: the message sits directly below it.
"Couldn't end … : …" : tmux couldn't end that session, usually because it had already ended. The list refreshes.
"No sessions are idle that long." : Tidy up found nothing to end for the time you chose; nothing was changed.
"Notifications are blocked for this site. Allow them in your browser’s site settings, then try again." : You (or your browser) refused the permission question earlier. Open your browser's site settings for roamd, allow notifications, then turn the switch on again.
"Notifications weren't allowed, so none will be shown." : The permission question was closed without an answer. Turn the switch on again and press Allow when your browser asks.
"On iPhone and iPad, install roamd to the Home Screen first, then turn notifications on from there." : Apple only delivers notifications to an app on the Home Screen. Install roamd (Share, then Add to Home Screen), open it from there, and turn notifications on.
"This browser can't show notifications from websites." : Your browser doesn't offer them for websites (or this is a private window). Chrome, Edge, Brave, Firefox and Safari do.
"Couldn't turn on notifications: …" : Your browser or our server refused the last step. If it says too many browsers are subscribed, turn notifications off on one you no longer use. Otherwise try again later.
No notification arrives
: Open Notifications in the main menu and choose Send test notification. Browser
permission and agent setup are separate. For Codex, update roamd, run roamd notifications
on that computer, restart Codex and trust the roamd hooks in /hooks. Check that both
Input needed and AI reply finished appear in the inbox. The setup panel says
Waiting for the first agent event until one arrives. A Delivery failed status
points to delivery rather than missing agent events. Also check machine mutes and the
device's Focus/notification settings. See the setup guide.
"Your organisation has switched this account off. Ask its admin." : An admin of the organisation you belong to switched your roamd account off, so you can't log in. Ask them to switch it back on. Your computers and vault are untouched. You'll have had an email when it happened.
"You already belong to an organisation." / "You already belong to an organisation. Leave it first." : A person can be in one organisation at a time. Leave the one you're in (Account → Organisation → Leave), then make or join another.
"You're the only owner. Make someone else an owner first, or delete the organisation." : Someone has to run the organisation. On the Organisation page make another person an owner, then leave; or delete the organisation from Account.
"Only an admin can do that." / "Only an owner can do that." / "An admin can only do that to members." : Inviting, switching off and removing are for admins; changing roles and deleting the organisation are for owners; and an admin can't act on another admin or an owner. Ask an owner.
"That address is already in your organisation." : They already belong. Look for them in the list on the Organisation page.
"Give the organisation a name." : The name was empty. Type one.
"Your organisation requires an authenticator app or a passkey as your second step. Set one up on Account to carry on." / "Your organisation requires a passkey as your second step. Add one on Account and choose it to carry on." : Your organisation's rules don't allow the second step you use now (an emailed code, or an app). Until you change it, your computers are out of reach; your account, vault and the Account page still work. On Account → Second step for new browsers choose an authenticator app or a passkey, as the message says.
"Your organisation doesn't allow sharing machines." / "Your organisation only allows sharing with people inside it." : Your organisation's rule on sharing stops you inviting that address. Ask an admin, or share with someone inside the organisation.
"Your organisation doesn't allow machines to be shared with you." / "Your organisation only allows you to use machines shared by people inside it." : Your organisation's rule stops you accepting or using a machine shared by someone outside it. A guest connection that was working stops when the rule is tightened.
"That isn't one of the choices." : A rule, or how long the audit log is kept, was set to something the page doesn't offer. Pick from the lists.
"Couldn't read the log." : On Organisation → Audit log, the page could not get the log: you may have lost admin rights, the connection dropped, or the date range is nonsense. Reload the page; if you are still an admin it comes back. The spreadsheet download is the same log.
The audit log is empty, or is missing older lines. : It only holds what happened while a person was in the organisation, and only for as long as an owner chose to keep it: older lines are not shown. Connections appear only if an owner turned that on, and each one is written when it ends. A filter that matches nothing says "Nothing in the log for this choice.": set the filters back to everyone and everything.
On the computer¶
"That address is on a private network…" (setting up a server from the website)
: roamd's website can only reach servers on the internet. Use roamd install-over-ssh
from a computer on the same network instead.
"Couldn't connect to that server…" or "…not as an SSH server" : Check the address and port, and that the server accepts SSH from the internet (a firewall may only allow some addresses).
"That doesn't look like a server address." / "The port must be a number." / "Couldn't find a server with that name." : Check the address and port you typed. Use a name or an IP address on its own, with the port in its own box.
"Enter the password, or paste a private key." : Setting up a server from the website needs one of the two. Fill one in.
"Couldn't use that key: …" / "Couldn't log in: …" / "Couldn't check that server (…)." / "Couldn't reach the server: …" : The private key couldn't be read, the login failed for a reason other than a wrong password, or the website couldn't talk to the server. The rest says why. Check the key, address and network, then Set up again.
"Too many server setups for now…"
: Setups through the website are limited for each account. Wait, or use
roamd install-over-ssh from your own computer.
The fingerprint doesn't match : Don't go on. Check you typed the right address. If it's right, someone may be intercepting the connection: use another network, or set it up from your own computer.
"The server refused that username and password or key."
: Check them by logging in with ssh yourself. Some servers don't accept passwords at
all: use a key.
"This key is protected by a passphrase…" : Enter the key's passphrase in the field that appears, then Set up again.
"install-over-ssh needs the ssh command (OpenSSH) on this computer" : Install OpenSSH (on Windows: Settings, then Optional features, then OpenSSH Client).
"setting up … didn't finish (see above)"
: One step on the server failed; the message above says which. Common causes: a wrong ssh
password or key, no curl on the server, logging in as root without --allow-root, or typing n at the
pairing code. Fix it and run the same command again. If the server had already been
approved, it appears twice in Open sessions: remove the one that stays offline.
"Setup didn't finish: the server's messages above say why." : The set-up on the server stopped and its own messages, shown above this line, say which step failed. See "setting up … didn't finish (see above)" for the usual causes.
"✗ The codes are different. Something was swapped on the way, so this page told your server no, and nothing was trusted. …" and "Stopped: the pairing codes were different, so nothing was trusted." : While setting up a server from the website, the code your server worked out didn't match the one your browser worked out. Something between them changed what was sent. Don't go on from this network: try again from another one, or set the server up from your own computer. If it had been added, remove it from Open sessions.
"Your server didn't show its pairing code, so nothing was trusted. Set up again." : The server stopped, or took too long. Set up again.
"Login didn't finish. roamd is installed; run roamd login to try again."
: The installer started roamd login for you, but you didn't finish it (closed it, or
typed n). roamd is installed. Run roamd login again.
"winget could not install psmux." / "winget could not install PowerShell 7." (Windows installer)
: The installer's offer to install psmux (tmux for Windows) or PowerShell 7 didn't work. roamd
still installed. Without psmux you get a plain shell; without PowerShell 7, sessions aren't
brought back after you log in again. The installer prints the command to try yourself
(winget install psmux, winget install Microsoft.PowerShell); afterwards run
roamd tmux-restore on.
"roamd can't start: other accounts (…) can use its data folder" (Windows)
: roamd keeps its keys in a folder only you should be able to open, and refuses to start if
another account can too. The message prints one command between >>> COPY AND RUN THIS
COMMAND, THEN RUN roamd AGAIN <<< lines: copy it, run it in PowerShell or cmd, then run
roamd again. It uses your account's ID rather than %USERNAME%, because PowerShell
doesn't expand %USERNAME% (that gives "No mapping between account names and security IDs").
Two screens on one Windows session flash or flicker
: You need psmux 3.4.0 or later (13 October 2026). Check with psmux -v; 3.3.8 builds
flicker. See Updating psmux on Windows (Install page) for the steps,
then psmux kill-server and rejoin the session.
psmux is "not recognized" after updating it (Windows)
: The window you are in was opened before the PATH changed. Open a new PowerShell, or refresh
this one: $env:Path = [Environment]::GetEnvironmentVariable("Path","User") + ";" +
[Environment]::GetEnvironmentVariable("Path","Machine"). If it still isn't found, the PATH
line didn't save: run it again (see Updating psmux on Windows (Install page)).
cargo install psmux fails with LNK1104: cannot open file 'msvcrt.lib'
: Your Visual Studio lacks the C++ build tools. Don't build it: use the ready-made zip from
the psmux releases page instead (see Updating psmux on Windows (Install page)).
"Multiple installed packages found" from winget uninstall psmux
: psmux is installed twice: once by winget (marlocarlo.psmux) and once by its own setup program
(ARP\User\X64\psmux). Name one: winget uninstall --id marlocarlo.psmux.
"Next: register this machine. There's no keyboard to ask you on here, so run: roamd login"
: The installer couldn't ask you questions (it was run by a script, not a person). Run
roamd login yourself in a terminal.
"roamd install: …" (the installer stops) : The installer stopped, and nothing was installed. "needs curl or wget": install one of them. "could not download …": check the computer's connection to roamd's website. "checksum mismatch for …; not installing" or "no published checksum for …; not installing": the file is damaged or not what was published; try again later or from another network. "no roamd build for … yet": that system or processor isn't supported. "on Windows, use PowerShell": use the Windows command from Add a machine. "roamd needs 64-bit Windows": the same, for a 32-bit PC.
Black windows flash up every few seconds on Windows
: Older versions of roamd did this when the computer also had a tmux program (for example
from Git for Windows): each time roamd looked at your sessions, Windows showed that
program's window for a moment. Update roamd (Account, then the machine, then Update) and
it stops. Until then, stopping and starting the task from PowerShell
(Stop-ScheduledTask -TaskName roamd) pauses it.
roamd: command not found just after installing
: The installer added roamd's folder to your PATH, but this terminal started before that.
Open a new terminal, or run the export PATH=… line the installer printed.
"roamd: connection lost: …" / "roamd: hub closed the connection" (in its messages) : roamd on the computer lost its link to roamd's website (the network dropped, or the website restarted) and is reconnecting by itself, waiting a little longer between tries. Nothing to do. If the computer stays offline in Open sessions, check its internet connection.
"roamd: stopped; the service will stay stopped until this is fixed." (in its messages)
: roamd stopped on purpose, so the service doesn't keep retrying something that can't work.
The line above it says why (for example the computer was removed from your account, or
its settings aren't private). Fix that, then run roamd service install or start
roamd run.
"this machine isn't registered yet; run roamd login first"
: Run roamd login and approve it in your browser.
"Couldn't set roamd up to run in the background: …"
: Login worked, but roamd couldn't set itself up to start automatically. The rest of the
message says why. Run roamd service install to try again, or roamd run to start it
for now.
"… Nothing was changed; try again, or remove it in the web app first." (roamd logout) : roamd couldn't tell the website to remove this computer, so it kept its registration. Try again when the computer is online, or remove it under Open sessions in the browser.
"could not save roamd's key in your Keychain" (Mac)
: roamd login couldn't store roamd's key in your login keychain. Unlock the keychain (log
in to the Mac's desktop, not only over SSH) and run roamd login again.
"roamd would like to record this computer's screen" (Mac) : roamd never looks at the screen. A program running in one of your sessions asked, and roamd versions before this fix were named instead of that program. Click Deny: roamd keeps working, and only the program that wanted the screenshot can't take it. Update roamd and the question names the program (or tmux, which runs your sessions). Sessions started before the update are still named as roamd until tmux restarts.
"roamd's block in your tmux config has lost its end line, so roamd won't rewrite the file. …"
: Someone edited the part of your tmux config that roamd manages, and roamd won't guess.
Delete that block by hand (from its start line), or put the end line back, then run
roamd tmux-restore on again.
"Couldn't set up bringing tmux sessions back after a restart: …" / "couldn't fetch tmux-resurrect: …"
: Shown by roamd service install. roamd is set up to start by itself, but couldn't fetch or
check the add-ons that save and restore tmux sessions, or couldn't write the tmux config.
Check the computer's internet connection, then run roamd tmux-restore on.
"… doesn't look like roamd's settings, so it was left alone"
: roamd uninstall was pointed (with --config) at a folder that isn't roamd's, so it
didn't delete it. Check the folder name, or leave --config off.
"Couldn't do: … (…)" at the end of roamd uninstall
: That one step failed and the rest still ran. The brackets say why. For "took this machine
off your account", remove the computer from Open sessions in the browser.
"this machine was removed from its account; run roamd login to add it again"
: The computer was removed (in Open sessions or with roamd logout). Run roamd login to
add it back.
"the hub address must be a plain https:// address (got …)"
: The address you gave roamd login has a name and @ in it, or spaces. That trick can
make an address look like one website while going to another. Use just
https://app.roamd.co.uk.
"refusing to run as root/Administrator without --allow-root: …"
: roamd gives every approved browser full control of the account it runs as, so it only
runs as the all-powerful admin account if you say so. Run it as your normal user, or add
--allow-root to roamd login, roamd run and roamd service install if you accept
that.
"This is the root account, so every browser you approve would get full control of this machine. Nothing was installed. …"
: You set up a server over SSH as root. To go ahead anyway, tick
Allow root / Administrator on the website (or add --allow-root to
roamd install-over-ssh) and set up again. Or log in as a normal user instead.
"other users can read or change …. Fix with: chmod 600 '…'"
: Another user on the computer could read roamd's secret files. Run the chmod command
shown, exactly as printed.
"… was sealed on another machine or user (or has been changed), so it can't be used here."
: roamd's settings were copied from another computer or user. Sealed settings only work
where they were created. Run roamd login to set this computer up afresh.
"roamd's keys are locked in your desktop keyring, which is … Log in to your desktop (or unlock the keyring) so roamd can use them."
: On Linux, roamd login put roamd's keys in your desktop keyring, and the keyring isn't
open yet (typically: the computer restarted and nobody has logged in to the desktop).
Log in to the desktop and roamd carries on by itself. For a computer that must work with
nobody logged in, delete roamd's settings folder and run roamd login --no-keyring.
"roamd's key isn't in your desktop keyring any more, so this machine's saved identity can't be opened. To start again, delete … and run roamd login."
: roamd's entry was removed from the keyring (or the keyring was reset). Do what it says:
delete the folder it names, run roamd login, and remove the old copy of this computer
in Open sessions.
"the code expired before anyone approved it"
: Approve soon after running roamd login. If it has been a while, run it again.
"this version of roamd is out of date; install the latest to add machines"
: The roamd on this computer is older than the website. Install it again (see
Installation), then run roamd login.
"pairing code not confirmed; nothing was trusted"
: You typed n (or anything but y). Nothing changed. Run roamd login again and
compare the codes carefully.
A Mac that stays on "Connecting"¶
The web app says "Still connecting to … This is taking longer than usual." (with a Troubleshoot your connection link to this section) when a computer hasn't answered after about eight seconds. If the computer is a Mac, the usual reason is a macOS prompt on the Mac's own screen, for example asking whether roamd may use your Documents folder. The web app can't see that prompt, so the connection waits until someone answers it.
- Go to the Mac and look for a pop-up from roamd (or from Terminal) asking for access to a folder.
- Choose Allow (or OK). The connection carries on by itself.
- If there is no prompt, check the Mac is awake and online, and that it shows as online in Open sessions. A Mac that has gone to sleep can't answer until it wakes.
Existing Mac releases can ask again after updates because they do not have a stable Mac signing identity. The release process now requires that identity, so macOS can recognise later versions as the same program. This needs a new signed release; the first change to that identity may ask once more. Permission reuse still needs checking on a real Mac. Signing does not grant access you refused, and roamd does not reset your Mac's privacy settings or require Full Disk Access as a workaround. The same wait looks like a slow connection from any other computer too: check that it is on and connected to the internet.
Mac: "cannot be opened because the developer cannot be verified" : Install with the Terminal command from Installation rather than downloading in the browser.
Conversation view cannot read or send¶
"Update roamd on {machine} to use Conversation view." : Update roamd on that computer. Updating the website alone does not add the machine-side reader and input checks.
"This session has no linked Claude or Codex conversation." : For Codex, use Choose conversation and select the open chat by name, folder and ID. Several terminals can share one Codex server, so tmux alone cannot identify the chat on each screen. The selected name tells you where Send and Stop go. Use tmux output for the terminal, or approved roamd hooks for an agent that runs under that terminal. roamd will not guess from a folder.
"Couldn't reach Codex's local server. Open Codex and try again." : The picker needs Codex's running local background server. Open Codex on that machine, then refresh the picker. Codex connected to a server on another computer is not supported by this picker; use tmux output for that terminal.
"That Codex conversation is no longer open. Choose another." : Refresh the picker and select an open conversation. roamd does not reopen a closed conversation or retry your message automatically.
"Open the terminal to answer this prompt." : Use the terminal icon to answer the agent's question or approval request.
"The session changed. Refresh before sending." : The pane, agent or conversation changed. Let the view update and check the current terminal before sending your draft.
"Couldn't confirm sending. Check the terminal before trying again." : Your draft stays, but the message may already have arrived. Check the terminal before sending again; roamd does not retry it automatically.
"Couldn't read this session. Open the terminal and try again." : Check that the saved session is still running and reconnect if needed.
A file opened from the terminal will not save¶
"This file changed on the machine. Copy your edits, then refresh before saving." : Your agent or another editor changed the file. Your draft is still in the reader. Use Copy or Download to keep it, then Refresh and combine the changes.
"Open a small UTF-8 text file." : The reader needs a small text file saved as UTF-8, a common text format. Files can be outside the session's folder. Check the path and your account's permission to read it; saving also needs permission to write the file and its folder. Read-only files cannot be saved here. Neither can files with hard links, where several names point to the same stored file. Use the Files panel for other kinds of file. If a full path outside the session folder is still refused, update roamd on the computer.
"Couldn't open or save this file: {reason}" : The computer could not complete the operation. Check that you can read or write the file and that the disk has space. Copy your draft before retrying.
"Update roamd on {machine} to read and edit files." : The computer needs a released roamd version with the file reader. The web app alone cannot add this feature to an older daemon.
"Open files from a saved session on your own machine." : Use a saved session on a computer you own. Plain shells and shared machines do not support this reader.
changed file -> Copy draft -> Refresh -> combine -> Save
missing path -> check session folder -> retry
An agent seems stuck on a Mac¶
No recent progress. Check your Mac for a permission prompt. means roamd thinks the agent is still busy but has stopped making visible progress. A request to access Documents or another protected place may be waiting on the Mac's screen. Check that screen, or ask someone at the Mac to check it and decide whether to allow the request. The web app cannot approve it for you.
If there is no prompt, the agent may simply be taking time to finish a tool or request. You can keep waiting or use Dismiss to hide the notice for this stall. It clears when progress resumes or the task ends. Reloading or locking roamd forgets the dismissal. The notice belongs to that session, in either view.
Notice appears -> check the Mac's screen
Prompt present -> respond on the Mac
No prompt -> wait, or dismiss the notice
This warning needs the updated roamd on the Mac. It cannot recognise every agent or confirm that a permission window is open, and it does not send a push alert.
"returned 127" mentioning continuum_save.sh
: A failed tmux run-shell command can open tmux's output view over an existing pane.
The exit status refers to the save command, not the AI process in the pane. A stale
background service can cause this by using a plugin path in a removed temporary
folder. Dismiss the error view with Ctrl+C while it is visible, then check the
service's configuration and plugin path. A second service must use its own tmux
server and configuration if it has separate plugins. Stopping the real tmux server
would terminate its sessions and is not needed to dismiss this view.
```text
Background helper -> missing save script -> tmux output view
|
Ctrl+C
|
Existing pane returns
```
Browser¶
| Message | Cause | Fix |
|---|---|---|
Couldn't reach roamd. Check your connection and try again. |
The browser couldn't reach the hub at all (offline, or dropped mid-request); nothing was changed | Retry when online |
Couldn't reach roamd to end your session there. This browser is locked; log out again when you're back online. |
Log out with no connection: the vault key is dropped here at once, the hub's session stays open | Log out again online |
roamd couldn't check your organisation's rules just now. Try again in a moment. |
The hub couldn't read the organisation's rules or membership, so it refuses instead of treating it as "no rules" | Retry |
Your access to this machine has ended. |
A guest's key was removed or its time ran out while a terminal or command was open (also shown on a request made after that) | Ask the owner to share again |
a guest who can only watch reaches only the folder files are sent to |
A watch-only guest asked for a file or folder outside the upload folder | Use the upload folder |
Still connecting to <machine>. This is taking longer than usual. with a Troubleshoot your connection link to this page |
A first connection took more than about eight seconds. A Mac waiting for someone to answer a macOS folder-access prompt looks exactly like this, and the page cannot see the prompt. The link opens in a new tab, so the attempt carries on | Answer the prompt on the Mac; it connects by itself. Otherwise check the machine is on, awake and online |
Wrong email or master password. |
Login refused (wrong password and unknown email look the same, by design) | Retry, or recover with the recovery key |
Too many tries. Wait a minute and try again. |
Guessing limit reached (per visitor, per email from one visitor, or per email overall) | Wait a minute; if it keeps happening from your usual computer, wait an hour |
That address has been sent several emails already. Try again later. |
That address got its share of sign-up codes or invitations (they can be made to happen by anyone) | Wait; check spam and earlier emails |
| "Check your email" after sign-up, but the email says the address has an account | Sign-up for a taken address: answered like any other, the owner is emailed a notice instead of a code | Log in, or recover with the recovery key |
That sign-up waited too long. Please fill in the form again. |
The pending sign-up expired or ran out of code tries | Start again |
That login waited too long. Please log in again. |
The emailed code wasn't entered while the proved login was still waiting | Log in again |
| "Check your authenticator app" form | New browser, second step = app (TOTP); no email is sent | Enter the app's current code |
On a browser new to this account, log in with your master password first… |
Passkey-only login on a new browser when the second step is a passkey | Password first, then the passkey |
That's your last passkey, and a passkey is your second step. Choose another second step first. |
Removing the only passkey while it is the second step for new browsers | Change the second step first |
Add a passkey first (above), then choose it here. |
Choosing the passkey second step with no passkeys | Add one |
That's already your second step. |
Changing to the current choice | Nothing to do |
That code isn't right. Check it and try again. (second step) |
Wrong emailed or app code while changing the second step | Retype |
That took too long. Please start again. |
The second-step change expired | Start again |
That reset waited too long. Please start again. |
The recovery code wasn't entered in time | Start again |
That email already has an account. Log in instead. |
Only on a hub that sends no email (development) | Log in |
Your master password is wrong. (removing a passkey) |
Removal re-checks the current password | Retype |
| "Check your email" form after the password | Right password from a browser unknown to the account; a code was emailed | Enter the code; if unexpected, change the password |
That passkey isn't set up for roamd. Log in with your master password. |
Assertion refused: unknown or removed credential, wrong account, bad signature or origin, or a counter that went backwards | Log in with the password; re-add the passkey |
The passkey request was cancelled or timed out. |
The browser's WebAuthn call was dismissed or timed out | Retry |
that passkey request has expired; try again |
The hub's challenge expired or was already used | Retry |
| "Check your email" form after a passkey | Verified passkey from a browser unknown to the account; a code was emailed | Enter the code; if unexpected, remove the passkey and change the password |
Your organisation has switched this account off. Ask its admin. |
The account's organisation switched it off; the login is refused after the password and second step | An admin switches it back on |
You already belong to an organisation. / … Leave it first. |
Making or joining a second organisation | Leave the first |
You're the only owner. Make someone else an owner first, or delete the organisation. |
The only owner tried to leave | Make another owner, or delete the organisation |
An organisation needs at least one owner. |
The only owner was changed to another role | Make someone else an owner first |
Only an admin can do that. / Only an owner can do that. |
A member invited or removed; an admin changed roles or deleted the organisation | Ask an owner |
An admin can only do that to members. |
An admin tried to remove or switch off an admin or an owner | An owner does it |
To go yourself, use Leave. |
Removing or switching off yourself | Use Leave on Account |
That address is already in your organisation. |
Inviting someone who is already in | Nothing to do |
You're not in an organisation. |
An organisation action by an account that isn't in one | Make or join one |
Give the organisation a name. |
An empty or very long name | Type a name |
Your organisation requires an authenticator app or a passkey as your second step. Set one up on Account to carry on. / … a passkey … |
The organisation's second-step rule doesn't allow the account's current second step; requests that reach computers are refused until it does | Change the second step on Account, or an admin relaxes the rule |
Your organisation doesn't allow sharing machines. / … only allows sharing with people inside it. |
The inviter's organisation's sharing rule | Ask an admin, or invite a colleague |
Your organisation doesn't allow machines to be shared with you. / … only allows you to use machines shared by people inside it. |
The guest's organisation's sharing rule, on accepting (and on connecting) | Ask an admin |
That isn't one of the choices. |
A rule, or how long the audit log is kept, set to a value outside the lists | Choose from the lists |
Couldn't read the log. |
The Audit log request failed (no longer an admin, or offline) | Reload the page |
Nothing in the log for this choice. |
The audit log filters match no line | Set the filters back to everyone and everything |
This passkey can't unlock your vault, so roamd can't use it… |
The authenticator gave no PRF output | Use a PRF-capable passkey |
that passkey login has expired; start again |
The verified passkey login waited too long for its code | Start again |
Your master password is wrong. (adding a passkey) |
The current password didn't check out | Retype |
That passkey is already set up for this account. / …for a roamd account. |
The authenticator already holds this account's credential / the credential ID is registered to another account | Nothing to do / use another passkey |
This browser can't use passkeys. |
No WebAuthn support | Password login, or another browser |
That recovery key has a typo. Check each group of four. |
The key's built-in checksum failed; 0/1 are read as O/I |
Re-type |
Wrong email or recovery key. |
Recovery refused | Check email and key |
That code isn't right. Check the latest email from roamd. |
Wrong code, or a replaced one (confirmation or new-browser code) | Use the newest email |
That code has expired or had too many wrong tries. Email yourself a new one. |
Code expired or its try budget used up | Email me a new code |
Too many codes asked for. Wait a minute and try again. |
Per-account send limit | Wait |
Too many wrong codes, so codes are paused until tomorrow. … |
Daily per-account limit on wrong emailed codes reached; the owner is emailed | Wait a day; if it wasn't you, change the password |
roamd has no saved identity for …, so it won't connect… |
No pinned host fingerprint in the vault for this device (the hub's recorded one is never used) | roamd login on the machine to re-pair |
The settings saved on roamd's server are older than this browser expected, so roamd stopped. |
A response is older than revision marks known before its request, or omits a previously known item. Responses overtaken by concurrent saves are retried without warning | Refresh to the current web app first; if the refusal remains, use the server's copy only after confirming the restore |
roamd's server asked for weaker password protection… |
The hub sent Argon2 settings below the ones roamd creates accounts with; nothing was sent | Treat the hub as hostile if it persists |
Could not send a code: … |
The hub couldn't hand the email to the provider | Retry later |
| Connect disabled / "offline" | The agent isn't connected to the hub | roamd run, or roamd service install |
offline since … · roamd was stopped there |
The control connection ended with a goodbye (SIGTERM or Ctrl-C on the agent) | Start it again |
offline since … · the machine may be asleep or off, or have lost its internet |
The control connection ended without a goodbye (power, network, kill), or stopped answering the hub's pings for longer than its quiet limit and was closed by the hub | Switch it on, make sure it isn't asleep, or check its network |
| Snippets window has no app commands | The machine hasn't reported an AI app in this session yet, doesn't run one it knows, or runs an older roamd | Wait a few seconds; update the machine |
| Snippet shows Insert only | The text matches the risky-command pattern | Insert, read, press Enter |
| Could not save that: … (rename or group) | The vault update failed (network, or a conflict that didn't settle) | Retry |
| roamd … is out of date | The version the agent reported is older than the release the hub goes with | Update the agent |
| …is not presenting the identity you approved… | The machine's host key doesn't match the pinned identity | Treat as hostile unless you reinstalled; then remove and re-enrol |
| … didn't reveal the secret it promised, so there is no pairing code to show… | The machine's revealed pairing secret doesn't match its commitment | Type n on the machine; retry; treat repeats as interference |
| … didn't answer in time. Run roamd login there again for a new code. | The machine never revealed its secret before the approval expired | New roamd login |
| Login failed: … rejected the username, password or key. | The agent refused the browser key (not on its approved list) | roamd login on the machine |
| The code … is unknown or has expired… | Approval code expired, already used, or mistyped | New roamd login |
| Update roamd on …: it still trusts only the old key until then. | The agent refused the key-replacement request (predates it) | Update the agent; it switches when next reached |
| roamd on … is out of date, so it still trusts only your old browser key… | Same, on connect; the retired key was used to log in | Update the agent |
| Couldn't reach … yet; roamd will keep trying. | The switch failed for another reason (connection, identity check) | Leave a page open; retried periodically |
| This browser has no voice that runs on this device, so messages are shown here instead. | No local speech voice; online voices are never used | Install a system voice, or use another browser |
| Dictate needs the microphone: allow it for this site, then tap Dictate again. | getUserMedia refused; this can include browser or OS policy, not only an explicit denial | Check browser/site and OS microphone permissions; installed apps have no address-bar site controls |
| Getting speech ready: … of … MB / Starting speech… | The browser is downloading the speech model (first use), then starting it | Wait; nothing is listened to until it's ready |
| Dictate stopped: … | Recording, or getting or running the speech model, failed; the reason follows | See the speech model messages below |
| the speech model's list isn't signed by roamd | The list naming the model has no valid signature from the release key (changed, signed by another key, or damaged) | Retry; if it persists, the download site is serving something roamd didn't sign |
| the speech model's list is unreadable | Signed, but not in the expected shape | Retry; if it persists, report it |
| the speech model's list doesn't include … | The signed list doesn't name the model this page needs | The app and the download site are out of step: reload the page |
| the speech model's list is older than the one this browser already trusts | The list on offer is validly signed but older than one this browser has used, so it could name a model with a known flaw (refused) | Retry; if it persists, the download site is serving an old copy |
| … doesn't match what roamd signed | The downloaded model file differs from the signed checksum (refused, not cached) | Retry; if it persists, the download site's copy is wrong |
| Couldn't reach roamd to get the speech model, and none is saved on this device yet. | The list couldn't be fetched and this browser has no saved copy | Connect and try again |
| the speech model couldn't be downloaded (…) | The site refused or failed the model download; the status follows | Retry later |
| the speech engine couldn't be downloaded (…) | The engine file that runs the model couldn't be fetched | Reload the page; retry |
| the speech model wouldn't load (…) | The engine rejected a model that passed the checks | Reload the page; if it persists, report it |
| Could not save the voice setting: … | The vault item couldn't be saved | Check the connection and retry |
| Only the machine's owner can change this. | A guest's key asked to change the screen-text setting; the agent refused | Ask the owner |
| roamd: started tmux after a restart, so your sessions come back (agent log) | First run after a new boot with restoring on; continuum restores the last save | None |
| Couldn't set up bringing tmux sessions back after a restart: … (service install) | Fetching or checking a plugin failed, or the tmux config couldn't be written | Check the machine can reach GitHub; roamd tmux-restore on |
| couldn't fetch tmux-resurrect: … / …doesn't match its pinned checksum | Download failed, or the archive differs from the pinned one (refused) | Retry later; a lasting mismatch means GitHub's copy changed: update roamd |
| your tmux config already loads tmux-resurrect or tmux-continuum itself… | The user's own config sets the plugins up | Configure them there |
| Hands-free needs the microphone… | getUserMedia refused | Allow the microphone for this site |
| Hands-free stopped: … | Getting or running the speech model failed; the reason follows | See the speech model messages above; turn Hands-free on again |
| <name> runs an older roamd that can't update itself… | The agent refused the update subsystem (older than 0.2.0) | Update now runs the installer there |
| <name> hasn't answered. It may have updated and be restarting… | No reply to Update now within two minutes; the reply is sometimes lost as the machine restarts | Close it and look at Open sessions for the new version |
| The update failed: the installer didn't finish on the machine | The upgrade command didn't print roamd updated. (download failed, no curl/wget, non-POSIX shell) | Run the installer by hand, then roamd service install |
| The update failed: the update isn't signed by roamd | The manifest's signature is missing, damaged or from another key | None needed; nothing changed. Check the release was signed |
| The update failed: the update's notes are unreadable | Signed, but not in the expected shape | Re-issue the release |
| The update failed: already up to date | The release isn't strictly newer than the running version (downgrades are refused too) | None |
| The update failed: this update has no build for this system | The signed manifest lists no build for this OS and CPU | Re-issue the release with that build |
| The update failed: couldn't download the update: … | The agent couldn't fetch a file from its hub's download site | Check the machine's network |
| The update failed: the download doesn't match what was signed | The build's SHA-256 differs from the signed one | Retry; re-issue the release if it persists |
| The update failed: couldn't install the update: … | The new file couldn't be written beside the running one | Fix permissions on its folder, or install by hand |
| The update failed: the new version wouldn't start, so the old one was kept | The staged build didn't exit successfully printing roamd <version> when run with --version | Nothing was installed; report the platform |
| roamd: this new version couldn't start; trying again, and if it still can't the old one comes back. (service log) | A build on trial failed before it was up (for example it couldn't read its settings); the service retries and the second start rolls back | Wait; update again later |
| roamd: the new version didn't stay up, so the old one is back (access log / service log) | A build on trial started a second time before proving itself, so .old was restored | Update again later |
| The update failed: only an owner's key can update roamd | A guest key asked for apply | Ask an owner |
| Could not save the update setting: … / Could not check for a roamd update: … | The vault save failed / the release or version couldn't be read | Reload and retry |
| I didn't catch that. | No speech detected before the listening window ended | Check the microphone input; speak after the beep |
| You're offline. Reconnect to reach your machines. | The browser reports no network (offline event); the app page was served from the service worker's kept copy | Reconnect; the notice clears on the online event |
| Refresh button (Load the new version of roamd) at the header's far right, turning once as it appears | A new service worker installed and is waiting (a release changed the app), or another tab already let it take over | Press it: sends SKIP_WAITING, the new worker takes over and the page reloads. Any other reload also works: on pagehide the page sends SKIP_WAITING itself, and page navigations are network-first. Other open tabs are not reloaded; they keep the button until their own reload |
| This browser can't install roamd. Chrome, Edge, Brave and Safari can. | No beforeinstallprompt and not an Apple device (or already installed) | Use a supporting browser, or use roamd in a tab |
| No install notice on Android or desktop | The browser fires beforeinstallprompt only for an installable app that isn't installed yet, after a short while; or Not now was chosen (kept in this browser's localStorage) | Wait, or use Account → Install roamd on this device |
| App page shows a blank page or Loading… after an update | A kept page and its files disagree (rare; a worker update was interrupted) | Reload; if it persists, clear this site's data in the browser |
| Apple keyboard dictation repeats its first letters or word | Apple touch devices use one retained native text field for printable keys, dictation and composition. Native key defaults perform the edit; input reads the resulting value without depending on beforeinput or inputType. Composition completion uses the same baseline. A minimal changed range is translated into cursor movement, deletion and insertion without rewriting the unchanged suffix. Controls, paste, blur and reconnect end the context | Reload and retry. WebKit/Chromium tests cover mixed key events, repeated final events, middle corrections, composition, missing beforeinput, normal typing and reconnection. Physical Apple dictation remains unverified. Live corrections require the remote application to interpret cursor keys and Backspace as text editing; Compose is appropriate for programs with different key meanings |
| Apple dictation still repeats after updating | An iPhone trace confirms the DOM already contained ththis after successive th and this insertions, without a focus reset or duplicate transport send. The native field now has nonzero in-viewport geometry and an opaque layer with transparent text, rather than opacity zero/off-screen positioning. IME preview no longer moves or resizes that field. This removes a layout defect; causation and the dictation outcome still need a physical-device check. Account's opt-in input diagnostics records bounded, memory-only event at browser input, terminal emission and transport-write boundaries. The compact report keeps actual input values, input-event text and exact outgoing terminal data, with focus/reset ordering, selection positions and composition flags. JSON escapes terminal control characters. Dictated or typed words are included while recording is on; audio, remote terminal output, machine names and session names are not captured. Browser/build metadata identifies the executing client. Copy stops recording; clear/reload discards it, and nothing is transmitted automatically | Record one reproduction, copy the report and share it with support. Synthetic tests are not physical dictation verification |
| Phone keyboard dictation repeats a long block or a long phrase distorts the display | Overlapping deferred keyboard handlers and retained input could replay committed text. The handler now coalesces pending edits, gives composition a single delivery path and clears committed composition text outside screen-reader mode. Apple touch input uses a separate retained native edit path until an input boundary. The focused input stays one cell wide and the preview is bounded | Reload, then retry. Compose provides an editable draft for long dictation; synthetic event tests cover Chromium and WebKit, but do not certify every phone keyboard |
| Command-V does nothing in Safari, but Edit → Paste works | Older app code cancelled the keypress event that some Safari versions emit for Command shortcuts, suppressing native paste. The corrected handler leaves modifier shortcuts alone and cancels only characters it handles | Reload roamd, focus the terminal and retry Command-V; use the Mac menu bar's Edit → Paste until then |
| Allow clipboard access for this site, then tap Paste again. | navigator.clipboard.readText() was refused or needs a permission prompt | Allow the clipboard for the site, tap Paste again |
| Press and hold a line in the terminal to select it, then tap Copy. | Copy with no selection | Long-press a line first |
| Couldn't copy: allow clipboard access for this site. | navigator.clipboard.writeText() refused (the terminal's Copy, or the copy button beside a saved file's path) | Allow it in site settings |
| Search shows No matches | The term isn't in the terminal's scrollback (which is limited) | Try another term |
| You have … terminals open, the most this plan allows. Close one to open another. | The terminal limit applies and as many tabs are open (a tab that is only disconnected still counts) | Close a tab; connecting to a session that already has a tab goes to it instead |
| A tab is missing after a reload | Only tmux tabs are remembered; the session had ended, the machine was removed, or this browser's remembered list was never saved (a failed save is not retried until the next change) | Open it again from Open sessions |
| Connect to a machine first. | Files were sent or asked for with no terminal showing | Open a terminal, then retry |
| … is larger than the most roamd will send (… MB). / … will fetch (… MB). | The file is over the size limit (checked in the page, and again by the daemon) | Split or compress it |
| The owner of … hasn't allowed file transfer for you. | A guest key without the files mark in authorized_keys; the daemon refuses every put, list and get | The owner ticks Can send and fetch files for that share |
| That address already has access. Stop sharing first, then share again with the new limits. | The address already has a share with other limits; asking again would quietly keep the old ones | Stop sharing, then share again |
| that isn't a time a share can last (shown as Could not share: …) | The request named a term the hub doesn't offer | Choose one of the listed terms |
| a watch-only guest can only look at a session | A watch-only key asked for a shell, a command, or a join that isn't a plain join of one session | None; the owner can share again with a full terminal |
| Your access to this machine has ended. | The key's end time passed while connected; the connection is cut | The owner shares again |
| you can only join the sessions shared with you | A key given only some sessions asked for a shell, a command, or to join a session not on its list (or not running: it is never started) | The owner shares again with that session |
| you can only end the sessions shared with you, and rename none | A key given only some sessions asked to rename, or to end one not on its list | None |
| Update roamd on … to share only some of its sessions. | The machine answered unknown guest setting: see=… / type=…: its roamd is older than picking sessions | Update roamd there, then Codes match: let them in again |
| pick the sessions again: at least one, each by its name (shown as Could not share: …) | The invite's only list was empty, longer than allowed, repeated a name, or held a name tmux won't take | Pick again |
| this key may not manage sessions here | A guest key without the session permission asked to rename or end a session | The owner shares again with Can rename and end sessions |
| <guest> was disconnected from <machine>. / <guest> wasn't connected. / Could not disconnect: … | The result of Disconnect now; a cut guest is turned away for a few minutes | None |
| <guest>'s time has ended. | The owner changed files for a guest whose end time has passed | Stop sharing to clear them |
| Choose a whole number between 1 minute and 365 days. | The custom time is empty, not a whole number, or out of range; Save stays off | Correct the amount |
| they haven't been let in (shown with the change) | Change time on a share that isn't active yet | Let them in first |
| Update roamd on … to send and fetch files. | The subsystem isn't there (older roamd) | Update roamd on the machine |
| Waiting to reconnect to … then Saved to … | The connection dropped mid-transfer; the page waits for the tab to rejoin, then resumes from the offset the daemon reports | Nothing; Cancel stops it |
| Lost the connection to …. | The tab didn't rejoin in time, or the connection ended another way | Reconnect the tab, send again: it resumes by token only within the same page |
| … isn't a folder on this machine / give the folder's full path, or one starting with ~ | A typed path, or the folder shown for an owner's upload, isn't an existing absolute folder (a typed file then opens as a file) | Create the folder, or fix the path |
| couldn't save to …: … / couldn't write the file: … | The daemon's user can't write there (permissions, disk full) | Choose another folder or free space |
| that upload is still being received here; try again in a moment | A previous try holds the part file and didn't let go within the wait | Retry |
| more data arrived than the file's size / the file didn't all arrive; send it again to carry on | The upload ended with the wrong amount: nothing is saved as a file | Send again; it continues from the part |
| no such folder or file / … isn't a file / that's past the end of the file | A download path that doesn't exist, is a folder, or an offset beyond the file | Check the path |
| Nothing here matches that. / Nothing in this folder. | The listing came back with no entries: the filter matched none of the folder, or the folder is empty | Clear the filter |
| A long folder fills in as it scrolls | The machine returns the listing a page at a time and says how many matched; the list draws only the rows in view and asks for the next page near the end | Scroll, or filter |
| … already exists | mkdir or rename named something already in the folder (checked with symlink_metadata, so a dangling link counts) | Another name |
| that isn't a plain name (one name, no slashes) | The name was empty, ./.., over-long, had a slash, a control or invisible character, leading or trailing space, or (Windows) a reserved character | Another name |
| couldn't move it to the Bin: … | trash::delete failed (Linux: no usable Trash for that mount) or, on a Mac, the move into ~/.Trash failed (another volume, or privacy settings) | None from the panel; nothing was removed |
| that folder can't be deleted from here | trash named the home folder or a root | None |
| a guest who can only watch can't change files | mkdir, rename or trash from a guest key with no shell | The owner shares again with a terminal |
| that is too big to fetch at once (…) | zip added up more than the download limit, or too many files, before sending anything | Choose fewer |
| there's no session called … (the panel opens at home instead) | here named a session tmux doesn't have, or tmux isn't running | None |
| unknown request (showing a folder, new folder, rename, delete, zip) / that isn't a valid request | An older roamd on the machine doesn't know that request; or the sort or start wasn't understood. Opening at the terminal's folder quietly falls back to home | Update roamd on the machine |
| Couldn't read the record of … (offline, or running an older roamd). | The machine is offline, can't be reached with the saved identity, or doesn't have the activity subsystem | Turn it on or update roamd there |
| Nothing to show for this choice. | The filters match no entries | Choose everything |
| A guest sees fewer lines than the owner | The daemon returns only lines ending with the guest's own key fingerprint | Expected |
| Signed out …. It needs an emailed code to log in again. | An owner signed another browser out of My browsers: its session ended and its remembered-browser token was forgotten | Nothing; it logs in again with the password and a code |
| That isn't a roamd vault file. | The chosen file isn't JSON with the export marker, or an item in it is malformed | Choose the exported file |
| That file can't be opened with your vault: … | At least one item doesn't open with this vault at its saved revision (changed, damaged or another account's); nothing was saved | Use an export from this account, unchanged |
| A new recovery key takes over on …. Until then your current recovery key works. | A new key is waiting (made in Account → Recovery key, with a password check); it cannot recover until it takes over | Wait, or Cancel the new key, or recover with the current key (which cancels it) |
| Email A new recovery key was made for your roamd account | A new key was made; sent at once with no key in it | If not the owner: recover with the current key, which cancels it, then check Activity |
| Email Your roamd password was changed / Your roamd password was reset | The password changed, or recovery finished; sent at once, in the background, with no password or code in it | If it wasn't the owner: recover with the recovery key, then check Activity. No email at all: mail is off or failing (reported without contents) |
| No email about a new browser | Mail is off or failing (reported without contents), or the browser was already known | Check the hub's mail settings; the event still shows in Activity |
| Amber line on a tab's bottom edge, then it goes away | A tmux connection ended without Disconnect or a lock; the page is rejoining it (three tries a second apart; if the browser is offline it waits for the network instead) | Nothing; Disconnect cancels |
| Couldn't reach …. Press Reconnect to try again. | The rejoin tries all failed (machine off, no route, roamd stopped there) | Fix the cause; Reconnect. A machine that comes back with a new hub connection (a restart) is rejoined by itself |
| A plain shell can't be rejoined: it ended with the connection. Press Reconnect to start a new one. | The connection of a non-tmux shell ended | Reconnect (new shell); use tmux for lasting work |
| The tmux session "…" is no longer running on …. Press Reconnect to choose another. | The session was not in the machine's list when rejoining (restart without restore, or closed) | Reconnect, then pick or start a session |
| Card shows no session summary | No report the browser can use: the machine isn't online, has no tmux, runs a roamd from before reports, has no owner key approved, the report is older than one already seen, or its signature is not from the machine approved on this browser (or it is sealed for another key) | Check the machine is online with a current roamd and tmux; or reconnect it. A damaged or swapped report is dropped silently by design |
| no sessions | tmux reported no sessions (not the same as tmux missing, which shows nothing) | Start a session |
| Update roamd on this machine to rename or end sessions. | The machine's roamd doesn't offer the session-management request | Update roamd there |
| Choose another name: … | The new name failed the check before anything was sent | Use a name without : or ., not empty, not long |
| Ending … / Ended …. | Progress and result of ending sessions, shown directly under the list | Nothing to do |
| Couldn't rename … : … / Couldn't end … : … | tmux refused (name taken, session gone); its own message follows | Pick another name; the list is re-read |
| No sessions are idle that long. | Tidy up found no session that is idle (not working, not waiting) for that long | Nothing changed |
| Notifications are blocked for this site. Allow them in your browser’s site settings, then try again. | Notification.permission is denied | Allow notifications for the site in the browser, turn the switch on again |
| Notifications weren't allowed, so none will be shown. | The permission prompt was dismissed (default) | Turn on again and allow |
| On iPhone and iPad, install roamd to the Home Screen first, then turn notifications on from there. | Apple device, not running as an installed app | Install, open from the Home Screen, turn on |
| This browser can't show notifications from websites. | No Notification, PushManager or service worker | Use a supporting browser |
| Couldn't turn on notifications: … | pushManager.subscribe failed, or the hub refused the address (limits, not a push address) | Retry; turn off notifications on a browser you no longer use |
| Waiting for the first agent event | No agent hook event has reached the hub for this computer | Install and approve the Codex hooks, then verify both event types; see notifications |
| Delivery failed | A push attempt failed; acceptance and display are tracked separately | Send a test notification on that browser, check permission and network, and re-enable its subscription if needed |
| Couldn't load your account's activity. | The account's own events couldn't be fetched | Open Activity again |
| This computer's roamd is too old to say how busy it is. Update it from Open sessions. | Resources page: the computer's roamd takes no readings | Update roamd there |
| Couldn't reach this computer. It may be offline. | Resources page: the connection for the readings failed, and none were already here | Check it's online; the page asks again every 10 seconds |
| The two passwords are different. / The two new passwords are different. | Password and repeat differ (sign-up, reset, change) | Retype |
| Your current master password is wrong. / Your master password is wrong. (recovery key, password change) | The re-check of the current password failed | Retype |
| Too many invites. Wait a minute and try again. | Invitations answered 429 | Wait |
| Could not share: … | The hub refused the invite (that's your own address, that isn't a time a share can last, …); its reason follows | Correct and retry |
| Could not remove … / leave … / change that for … / stop sharing / accept … / decline … / approve: … | The hub refused or the request failed; its reason follows | Retry; reload |
| Approved, but its identity could not be saved to your vault: … | The approval went through but the pinned host identity could not be saved to the vault | Retry; roamd login again if the machine then shows has no saved identity |
| A snippet needs a name and a command. | Saving a snippet with an empty name or command | Fill both |
| Couldn't copy: select the key and copy it yourself. | navigator.clipboard.writeText() refused for the recovery key | Copy by hand |
| Could not start the change. / Could not check the code. / Could not save the change. / Your passkey was refused. | The second-step change failed without a reason from the hub | Start the change again |
| Could not replace the key: … | Replacing the browser key failed (vault save or hub request) | Retry |
| Could not save the locking setting: … / Could not save the voice settings: … / Could not save the setting: … | The vault item could not be saved | Check the connection and retry |
| Couldn't change it: … (session list, bringing sessions back) | The machine's restore change failed with the reason shown; a guest key is refused with Only the machine's owner can change this. | Fix the reason (network to the plugin source, tmux config) and retry |
| this key is no longer approved here | A request was sent on a connection whose key was removed from authorized_keys (for example roamd keys revoke) | roamd login on the machine |
| Not connected | The tab has no open terminal | Open one from Open sessions |
| that file is larger than this machine will accept | The daemon's own upload size cap | Split or compress |
| give the file's full path, or one starting with ~/ / too many files with that name | A download path that isn't absolute; or the folder already has many copies of the name | Give the full path; rename |
| The update failed: an update is already being installed / … already waiting to take effect | An install is in progress, or a build is on trial and hasn't proven itself | Wait, connect again |
| Enter the password, or paste a private key. | Web SSH setup with neither | Fill one in |
| That doesn't look like a server address. / The port must be a number. / Couldn't find a server with that name. | The hub's check of the address, port or DNS lookup in web SSH setup | Fix the address |
| Couldn't use that key: … / Couldn't log in: … / Couldn't check that server (…). / Couldn't reach the server: … / Setup didn't finish: the server's messages above say why. | Web SSH setup failed at that step; the reason follows | Fix and Set up again |
| I didn't catch that. Tap Dictate to try again. | The model returned no words for the recording | Retry nearer the microphone |
| Hands-free needs the microphone: allow it for this site, then try again. | getUserMedia refused when turning Hands-free on; it switches itself off | Allow the microphone, tap Hands-free |
| A machine asked for a knock but nothing arrived | Muted machine; no subscribed browser; the push service dropped the message (the address is forgotten if it says it is gone); a focused page is not interrupted; the knock rate limit | Check mute and the switch; turn it off and on to subscribe afresh |
Dictate requests `getUserMedia` within the initiating tap, including first-use consent,
before awaiting the settings write or speech engine. Recording starts only after the
engine is ready. Cancellation during permission or loading and engine failures release
the stream unless Hands-free is using it. Automated Chromium and WebKit tests check the
request ordering, muted stream reuse between completed recordings, and cleanup on
backgrounding with simulated permissions; actual installed-phone prompts
are not verified by those tests.
```text
Dictate / first-use OK -> getUserMedia -> speech ready -> record
| |
refused/cancelled failed/cancelled
+------- release mic ------+
```
## Agent (`roamd`)
| Message | Cause | Fix |
|---|---|---|
| ``this machine isn't registered yet; run `roamd login` first`` | No enrolment in the settings folder | `roamd login` (check `--config`) |
| ``this machine was removed from its account; run `roamd login` to add it again`` | The hub rejected the device token | Re-enrol |
| `refusing to run as root/Administrator without --allow-root: …` | `login`, `run` or `service install` as root or elevated | Run as a normal user, or add `--allow-root` deliberately |
| `This is the root account, so every browser you approve would get full control of this machine. Nothing was installed. …` (SSH setup output) | Setup script found `id -u` = 0 without `--allow-root` | Tick **Allow root / Administrator** (web) or pass `--allow-root` (`install-over-ssh`); or use a normal account |
| `Stopped: that login is root. Tick “Allow root / Administrator” and Set up again to go ahead anyway.` (web) | The same, seen by the web page | As above |
| `✗ The codes are different. Something was swapped on the way, so this page told your server no, and nothing was trusted. …` / `Stopped: the pairing codes were different, so nothing was trusted.` (web SSH setup) | The machine's printed pairing code differs from the browser's: `fp(H)`, `Nm`, `B` or `Nb` was altered in transit | Page answered `n`; retry from another network; remove the stray offline device |
| `Your server didn't show its pairing code, so nothing was trusted. Set up again.` (web) | No `Pairing code:` line before the wait ran out | Page answered `n`; set up again |
| `roamd: command not found` after install | Installer appended the folder to login files; current shell predates it | New login shell, or the printed `export PATH=…`; `ROAMD_NO_MODIFY_PATH=1` means it was left to you |
| `other users can change DIR. Fix with: chmod 700 'DIR'` | Settings folder writable by others | `chmod 700` |
| `other users can read or change FILE. Fix with: chmod 600 'FILE'` | A secret file readable by others | `chmod 600` |
| `FILE is a link; roamd only uses its own files…` | A symlink in place of a settings file | Replace with a regular file |
| `FILE belongs to another user` | File owned by a different user | Fix ownership or use your own `--config` |
| `…was sealed on another machine or user (or has been changed)…` | Settings copied from elsewhere, or modified | `roamd login` to re-enrol |
| `roamd's keys are locked in your desktop keyring, which is … Log in to your desktop (or unlock the keyring) so roamd can use them.` | Linux: settings sealed with a desktop-keyring key, and the keyring is locked, not running or has no default collection; `roamd run` retries | Log in to the desktop; or re-enrol with `--no-keyring` |
| ``roamd's key isn't in your desktop keyring any more…`` | The keyring entry for this settings folder is gone | Delete the settings folder, `roamd login` |
| `the hub address must start with https:// (got …)` | Plain HTTP is only allowed to localhost | Use an `https://` hub |
| `the hub address must be a plain https:// address (got …)` | The address has a `user@` part (which can hide the real host) or spaces | Use just `https://host` |
| `this version of roamd is out of date; install the latest to add machines` | Agent predates pairing secrets | Reinstall, then `roamd login` |
| `the code expired before anyone approved it` | Not approved in time | Re-run |
| `pairing code not confirmed; nothing was trusted` | Anything but `y` at the prompt | Re-run and compare |
| `could not reach the hub: …` | Network, DNS, TLS or proxy failure | Check connectivity to the hub |
| `install-over-ssh needs the ssh command (OpenSSH) on this computer` | No `ssh` on the PATH | Install the OpenSSH client |
| `That address is on a private network…` (web setup) | The name resolved only to non-public addresses, or to the hub itself | Use `install-over-ssh` from inside that network |
| `Use the SSH port (22) or a port from 1024 up.` | Low ports other than SSH are refused | Use the server's SSH port |
| `Couldn't connect to that server…` / `…not as an SSH server.` | TCP connect failed or timed out, or the first line wasn't an SSH greeting | Check address, port and firewall |
| `Too many server setups for now…` | Per-account limit on relayed setups | Wait |
| `The server refused that username and password or key.` | SSH authentication failed (servers may disable passwords) | Check with `ssh`; use a key |
| `setting up … didn't finish (see above)` | ssh or a remote step exited non-zero (auth, missing `curl`, root without `--allow-root`, pairing declined, service install) | Fix the reported step and re-run; a run that failed after enrolment leaves an extra (offline) device to remove |
| `roamd install: needs curl or wget` / `could not download …` / `checksum mismatch for …; not installing` / `no published checksum for …; not installing` / `no roamd build for … yet` / `roamd needs 64-bit Windows (this PC reports '…').` | The installer refused: missing downloader, failed download, hash differs from `SHA256SUMS`, or no build for this OS or CPU; nothing was installed | Check network; retry; use a supported system |
| `could not save roamd's key in your Keychain` | macOS: `security add-generic-password` failed (locked keychain, no GUI session) | Unlock the keychain; `roamd login` |
| Repeated Mac folder permission prompts after updating | Existing Intel releases have no Mac code signature; Apple Silicon releases use an ad-hoc identity. TCC cannot reliably carry consent across these builds. The release process now requires Developer ID Application signing with a stable identifier and Apple Team ID before checksums. The minisign update signature serves a separate purpose and cannot preserve TCC identity | A new signed release is needed. Allow the requested folder if wanted on the first identity transition; keep the installation path stable. Native testing across two signed versions remains outstanding. Do not reset TCC or grant Full Disk Access to work around a changing identity |
| "roamd would like to record this computer's screen" (or other privacy prompts naming roamd) | macOS charges a privacy request (TCC) to the *responsible* process. launchd starts roamd, so before this fix every tmux server, shell and AI app it started counted as roamd. roamd uses no screen, camera or microphone API. Now (`own.rs`) a session's tmux, shells, `tmux` queries and AI-app summaries start as `roamd __own <program> <args>`, which `posix_spawn`s the program with `POSIX_SPAWN_SETEXEC` (same pid, same descriptors, SIGPIPE back to default) and `responsibility_spawnattrs_setdisclaim`, so it answers for itself. That call isn't in Apple's headers; it is looked up with `dlsym`, and without it the program starts as before. Grants already given to roamd no longer cover sessions, so a session's program may ask once again. A tmux server started by an older roamd keeps the old attribution until it restarts. The macOS screen-recording prompt can't carry an app's own explanation, so nothing is added to it. Built and linked for macOS; **not yet run on a real Mac** | Deny it; update roamd |
| `roamd's block in your tmux config has lost its end line, so roamd won't rewrite the file. …` | The marked block was edited so its end marker is gone | Delete the block by hand, then `roamd tmux-restore on` |
| Console windows flashing on Windows, repeating | roamd frees its console when run by Task Scheduler, so each child it started (`tmux list-sessions`, `tmux list-panes`, from `Watcher`) got a new console window; fixed by starting every child with `CREATE_NO_WINDOW` (version 0.2.11); `ssh` and the install/status steps keep the caller's console | Update roamd |
| Windows machine shows offline after roamd updates, even after a refresh | Task Scheduler's restart-on-failure didn't start the new roamd after it exited for the update (task "Ready", Last Run Result `0x4B`) | Start it once by hand (`roamd run`, or run the `roamd` task in Task Scheduler); from the version after 0.2.18 the task starts roamd again within a minute by itself |
| `bringing psmux sessions back needs PowerShell 7 (pwsh), which isn't installed. …` | Windows: psmux's add-ons are PowerShell 7 scripts and `pwsh` wasn't found | `winget install Microsoft.PowerShell`, then `roamd tmux-restore on` |
| `couldn't read … as text …; roamd leaves it alone` | The tmux or psmux config was saved in a Windows encoding (UTF-16), which roamd will not write over | Re-save the file as UTF-8 (Notepad: Save As, Encoding: UTF-8), then turn restore on again |
| `roamd: connection lost: …` / `roamd: hub closed the connection` (log) | The control connection to the hub ended; roamd reconnects with backoff | None; check the network if it stays offline |
| `roamd: stopped; the service will stay stopped until this is fixed.` (log) | `roamd run` as a service ended with an error that retrying can't fix (removed device, unsafe settings); the line before names it | Fix it, then `roamd service install` |
| `roamd: stopped reporting session status: …` / `roamd: couldn't report session status to the hub: …` / `roamd: couldn't ask the hub for a notification: …` (log) | The sealed status or knock request to the hub failed; the reason follows | Check the network; restart roamd if the status stays missing |
| `no approved key … (see roamd keys)` | `roamd keys revoke` with a fingerprint that isn't in the list | Copy it from `roamd keys` |
| `The hub had already forgotten this machine.` / `… Nothing was changed; try again, or remove it in the web app first.` | `roamd logout`: the hub no longer knew the device (fine), or it could not be told (registration kept) | Retry, or remove the device in the web app |
| `install-over-ssh needs a server, like me@server` / `…one server at a time` / `unknown option -…` | Missing or extra server, or a server beginning with `-` | Give one `USER@SERVER`; ssh options go after `--` |
## Service logs
| OS | Where roamd's own messages go |
|---|---|
| Linux | `journalctl --user -u roamd.service` |
| macOS | `~/Library/Logs/roamd.log` |
| Windows | Not captured yet (known gap); logins are still in `access.log` |
## Document reader failures
| Message | Meaning | What to do |
|---|---|---|
| `Update roamd on {machine} to use Conversation view.` | The daemon lacks the conversation request | Update the machine daemon |
| `This session has no linked Claude or Codex conversation.` | No exact active transcript association; a shared Codex server does not expose each terminal client's displayed thread | Explicitly choose a loaded root conversation from the local Codex server, or use tmux output. Hook attribution requires live process ancestry; shared-server environment variables are insufficient |
| `Couldn't reach Codex's local server. Open Codex and try again.` | The local Codex protocol connection failed or rejected the request | Check the local Codex server and refresh the picker. Remote Codex servers are not supported by this picker |
| `That Codex conversation is no longer open. Choose another.` | The selected thread is closed, unavailable or a child agent | Refresh and choose an open root conversation; no implicit resume or input retry |
| `Open the terminal to answer this prompt.` | A known interactive approval/question is pending | Respond through the terminal |
| `The session changed. Refresh before sending.` | Pane, process start or conversation identity changed | Refresh and verify the current session before sending |
| `Couldn't confirm sending. Check the terminal before trying again.` | Input acknowledgement is uncertain | Inspect the terminal before retrying; input is never replayed automatically |
| `Couldn't read this session. Open the terminal and try again.` | Session capture or record read failed | Check that the session exists and reconnect if necessary |
| `This file changed on the machine. Copy your edits, then refresh before saving.` | The expected revision differs from the current file | Copy or download the retained draft, refresh, then merge manually |
| `Open a small UTF-8 text file.` | File type, encoding or size is unsuitable; edits may also have unsupported ownership or hard links | Use a small UTF-8 regular file; absolute and parent paths can reach other folders subject to OS permissions. Update the machine daemon if it still enforces the session-folder boundary; use the Files panel for general downloads |
| `Open files from a saved session on your own machine.` | No owned tmux session is associated with the originating terminal | Open a saved session as the owner |
| `Update roamd on {machine} to read and edit files.` | The daemon does not support document requests | Install a released daemon version with this feature |
| `Couldn't open or save this file: {reason}` | The operating system refused a file operation | Check the file and directory permissions and available disk space; keep the draft before retrying |
```
request fails -> draft remains -> copy or download
-> correct file / reconnect / refresh -> retry
```
File-reader support requires an updated daemon as well as the web app. A session
directory change can invalidate an earlier relative path. Save conflicts are detected
before replacement; a simultaneous external write can still race that final step.
### Suspected Mac permission stalls
**No recent progress. Check your Mac for a permission prompt.** is a heuristic
warning from the Mac daemon, based on active-agent evidence and unchanged
meaningful terminal output. It is not confirmation from macOS. Long-running
tools can look the same, and agents without recognised activity can be missed.
Explicit terminal input requests keep their normal input-required indication.
```text
Busy agent + paused progress -> suspected wait -> owner banner
Progress / task end -> warning clears
```
Check the remote Mac's graphical session for a privacy prompt. The browser cannot
answer it or determine which permission it requests. Dismissal is local to the
open tab and current stall; it is not saved across reload or lock. There is no
new push notification for a suspected stall. The detector and browser lifecycle
are tested with controlled inputs; real macOS prompt behaviour remains unverified.