Help › Reference

Troubleshooting

Symptoms and fixes: devices offline, installs and onboarding failing, screens and terminals not opening, security and compliance oddities, sign-in problems and emails not arriving.

Find your symptom below. Most fixes take a minute. If none of this helps, email us with what you saw and what you tried.

#Devices

#A device shows offline

1. Is the computer on and connected to the internet? Laptops go offline when closed. Try Wake it up on My computers.
2. Is the agent running? On the computer: Windows, open Services and check bananana-node is Running (start it if not); Mac, sudo launchctl list | grep bananana; Linux, systemctl status bananana-node. The tray icon says "the agent isn't running" when it's stopped.
3. Does the computer reach the relay? Open https://relay.bananana.dev/v1/health in its browser; it should say {"ok":true…}. A firewall or proxy blocking it is the usual cause in offices with strict internet filtering: allow outgoing HTTPS (port 443) to relay.bananana.dev.
4. Is the brain connected? If every device is offline at once, the Company overview says "The brain is not connected to the relay": check the brain's internet connection.

#A device keeps reconnecting

Usually a flaky Wi-Fi or a VPN that drops. bananana.dev reconnects by itself within seconds; work queued for the device waits. If it's constant, check the computer's network first.

#Tabs are missing on a device's page

Tabs follow the features the device allows and your permissions. No Terminal button or Files tab? The device didn't allow it: at the computer, run bananana-node enable terminal (or files, services, screen). No Security tab? Your role lacks "Security status".

#"Not read yet" for security or apps

The device's agent is older than the feature. Press Update agent to … on its Overview tab. Macs and Linux computers get new agents a little after Windows.

#Adding computers

#The code doesn't work

Codes expire after 10 minutes (unless you chose longer) and work once. Make a new one. If the person typed it wrong: codes never contain 0, O, 1, I or L, so check for 8 vs B, 5 vs S and 2 vs Z. After 30 wrong tries in an hour, that network has to wait an hour.

#Windows says "Windows protected your PC"

SmartScreen warns about apps it hasn't seen often. Choose More info, check the publisher, then Run anyway. In managed offices, use a deployment key through your deployment tool instead.

#The install command fails in PowerShell

• "Run PowerShell as Administrator": right-click PowerShell and choose Run as administrator.
• "running scripts is disabled": the command doesn't need script files, but some policies block it anyway. Use bananana-setup.exe from bananana.dev/setup instead.
• "Not installed": scroll up for the reason, usually an expired or already-used token.

#The computer joined but nothing works

It's probably waiting for approval (it joined with a code or key). Approve it on the Nodes page: Approving devices.

#Screen, terminal and files

#The screen stays black or says waiting

• Windows: someone must be signed in at the computer. If it's locked, you see the lock screen; if nobody is signed in, there's no screen to show yet.
• Mac: allow Screen Recording and Accessibility for bananana-node in System Settings › Privacy & Security, then try again.
• Linux: it needs an X11 session; Wayland isn't supported yet. Log in choosing an "Xorg" session.

#I can see the screen but can't click

Your role allows viewing, not control (helpdesk, for example), or on a Mac, Accessibility isn't allowed yet.

#It keeps asking me to sign in again

Terminal and screen control ask you to confirm it's you every 15 minutes. That's on purpose.

#Upload fails for big files

Through the public dashboard address, Cloudflare limits uploads to 100 MB per file. Use the brain's local address on the office network, or Finder or Explorer access.

#Apps and updates

#A required app isn't installing

1. Open Apps, the app, and find the device: what does its state say?
2. Failed: open Output. Common reasons are in The app catalog.
3. Missing for a long time: does the device allow Terminal? Is it approved and online?
4. No package: add a package id for that device's system.
5. Installed, but the catalog says missing: the detection pattern doesn't match the app's name in the device's list. Check the name on the device's Apps tab and adjust "Detected when".

#A rollout is stuck

A ring only moves on when it has waited its days and enough devices succeeded. Offline devices count as not done yet. Open Devices to see who's waiting; press Next ring now to move on anyway.

#Security and compliance

#An action says "Blocked"

Windows wouldn't allow it, and the reason is shown. Tamper Protection and Group Policy are the usual causes, and bananana.dev never works around them. Change the policy where it's set (Intune, Group Policy), or turn off Tamper Protection on that PC in Windows Security if you're sure.

#A firewall change "Rolled back"

The PC couldn't reach the relay after the change, so it was undone to keep the PC reachable. Check the rule doesn't block outgoing HTTPS.

#Compliance says "Unknown"

The device hasn't reported that check yet: it's new (wait a few minutes), its agent is old (update it), or it's offline. "Not checked" means the check doesn't apply to that system yet.

#Disk encryption shows Off but BitLocker is on

Press Read again on the Security tab. If BitLocker is still encrypting, it shows On once protection is active; suspended protection counts as off.

#Signing in

#I didn't get the code email

Check spam for mail from [email protected]. Codes expire after 10 minutes; ask for a new one. Set up an authenticator app so you don't depend on email.

#"Too many attempts. Wait 15 minutes"

Several wrong passwords from your network. Wait 15 minutes. If you forgot your password, an Admin can reset it.

#My account is suspended

Ask an Admin or Owner to set you back to Active on the Users page.

#Emails and alerts

#No alert emails

Check spam. Ask an Admin to send a test (configure_integrations.py alerts test on the brain). Alerts may be turned off, or a fixed list of recipients may be set without you.

#Too many alert emails

bananana.dev sends at most ten an hour and reminds once a day. Fix the cause and they stop; each email says how.