Troubleshooting
Start with the collector log: almost every problem shows up there with a clear message. The collector’s messages are in Portuguese; the main ones are below.
The machine doesn’t show up
| What to check | How |
|---|---|
| Log on Mac | tail -f ~/Library/Logs/fleetly-coletor.log |
| Log on Linux | journalctl -u fleetly-coletor -f |
| Log on Windows | Get-Content $env:USERPROFILE\.fleetly\collector\coletor.log -Wait |
| Is Claude Code signed in? | claude should open with your account |
| The collector’s Node | ~/.fleetly/node/bin/node -v (only exists if the machine had no Node 20) |
- "Não consegui abrir …/login" (couldn’t open the hub): the machine can’t reach the hub. Check outbound internet access and the network proxy.
- "Rode com o seu usuário, não como root": install as the user signed in to Claude Code.
- Mac, sessions in Documents or Desktop don’t show up: give Full Disk Access to the collector’s Node (see Connect machines).
- Mac, an agent opened by Fleetly can’t read OneDrive, iCloud or Dropbox ("Operation not permitted"): everything the Fleetly app opens inherits its privacy permissions, even if VS Code has its own. The chat explains why. At the Mac, in System Settings → Privacy & Security → Files and Folders (or Full Disk Access), allow Fleetly. Away from the Mac, a session open in VS Code can do the same. To know before you leave the Mac: in Settings → Chat, Mac permissions shows the folders Fleetly can’t read, with Open Mac Settings; and the collector app checks on its own: the first time, the Pastas protegidas do Mac step (“Protected Mac folders”) in the setup window lists each folder, opens Settings at Full Disk Access, shows ✓ once you turn Fleetly on and has Já liguei: reiniciar o Fleetly (“Done: restart Fleetly”) (macOS only applies it after a restart); and every time the app opens, if any is missing, it notifies you and adds Liberar pastas do Mac (“Allow Mac folders”) to the menu bar menu. A folder you don’t use drops out with Não uso essa pasta (“I don’t use this folder”). It can’t be allowed from afar: macOS only lets someone at the Mac do it.
"A central recusou o token" (the hub rejected the token)
The token was revoked, or the machine was removed from the building. Create a new command in Settings → Buildings → Machines → Add machine → With a command and run it on the machine: it replaces the token and restarts the service.
Approvals don’t reach the dashboard
- Check that the hooks are written: run
node ~/.fleetly/collector/fleetly-collector.mjs hooks. - For Codex, approve the Fleetly hooks: in VS Code, Review hooks → Allow all; in the terminal,
/hooks. - In Settings → Notifications and approvals, in Automatic mode, a request only comes to the dashboard after the idle time at the computer. To test, use Always here.
- If the log says port 4747 is in use, reinstall with
--hook-portand another free port. - The session must be inside the machine’s folders.
A session doesn’t show up
- It is outside the folders the machine shows (see Settings → Buildings → Machines).
- A filter is hiding it: check the active filters in the corner of the stage, or the number on the Filters button.
- Codex session: Codex must be signed in for the same user that runs the collector.
The session open in VS Code didn’t do what I asked
For a session open in VS Code or the terminal, the dashboard’s message arrives as a note, and the agent decides what to do with it. For the request to count as yours, use Take over in Fleetly or Continue in the Claude app (see Chatting with sessions).
That delivery uses Claude Code’s inbox, a format Anthropic doesn’t document and that may change in an update. If sending fails, the chat shows the error.
The preview won’t open
- "Nada respondendo em 127.0.0.1:<port>" (nothing answering): the dev server isn’t running, or is on another port. Start the app (for example
npm run dev) and try again. - "Não respondeu como um site" (didn’t answer like a website): the port belongs to another kind of service, such as a database.
- "A porta é do próprio Fleetly": the collector’s own ports never become a preview.
- "Esta prévia foi fechada" (this preview was closed): it timed out. Open it again from the dashboard.
I can’t reply or send work
The trial ended or the subscription is more than 3 days overdue, and the account is on Free: you see the agents and approve requests on one machine, but replying and sending work are part of Personal. Subscribing in Settings → Subscription unlocks it immediately. Nothing is deleted.
Didn’t find what you were looking for? Write to admin@fleetly.tools.