Troubleshooting
Error messages and what to do about them.
Find the message you're seeing, or the thing that's going wrong, and try the fix next to it. When in doubt, horus devices and horus status --log show what's happening.
In the app
| What happens | Try this |
|---|---|
| Sessions stop when I leave the app or turn the screen off. | Allow notifications and unrestricted battery use for Horus. Some brands add their own battery savers; see Running in the background. |
| Long builds or agents get cut off partway (Android 12+). | Run horus tune once from a computer. |
| Too many apps running | Stop a session from the list shown, or raise the limit in SETTINGS → Concurrent apps. Lower it if the phone struggles. |
| An agent's first install fails or hangs. | Check the phone's internet connection, then close the session and tap the agent again. The installer output in the terminal usually says what went wrong. |
| Setup stays on PREPARING… | Horus is downloading Alpine Linux. Check your connection and give it a few minutes. If it never finishes, close and reopen Horus. |
| A sign-in link in the terminal won't open. | Only links to localhost and to GitHub, Anthropic, Claude, OpenAI, ChatGPT and OpenCode open. For other links, copy the address into your browser. |
| My GitHub repositories don't show up. | Tap Refresh repositories. If it still says Not connected, log in to GitHub again from the home screen. |
| Too many incorrect attempts. Try again in … | Wait out the timer (up to 15 minutes). Forgotten passwords can't be recovered; clearing Horus's storage starts over and deletes your projects. |
| This folder is too large to copy | Copies to Downloads are limited to 20,000 files or 2 GB. Copy a smaller folder, or use horus cp from a computer. |
With the horus CLI
| Message | What to do |
|---|---|
adb was not found | Install Android platform-tools (setup steps), or point horus at it with ADB=/path/to/adb. |
No phone is connected | Check the cable carries data (try another), that USB debugging is on, and that you tapped Allow on the phone's prompt. Unlock the phone and replug if the prompt didn't appear. |
Horus is not installed on the connected phone | Install Horus on that phone, or unplug other Android devices. |
Open Horus on the phone and finish setup first | Open the app and create your password, then run the command again. |
That is not the Horus password | Use the password you set in the Horus app (not your phone's screen lock). Wrong tries count toward the app's lockout. |
Several phones are connected: … | Name one: horus ssh pixel. Use horus devices to see names and serials. |
… is not paired with this computer | Run horus pair for that phone. |
Remote access is off on … | Turn it on in Horus → SETTINGS → Remote access, or run horus pair again. |
Timed out waiting for the SSH server on the phone | Unlock the phone and open Horus, then try again. The very first start needs internet on the phone. |
The SSH server on the phone failed | Run horus status --log and look at the end of the log. Re-running horus pair often fixes it. |
| SSH warns the host key changed | Expected after reinstalling Horus or clearing its data. Run horus pair again to trust the phone's new identity. |
horus: command not found | npm's global folder isn't on your PATH. Open a new terminal window, or reinstall Node with a version manager like nvm. |
Linux: adb says "no permissions"
Your user isn't allowed to access USB devices yet. Many distributions fix this by adding your user to the plugdev group and installing Android's udev rules (often a package called android-udev-rules or android-sdk-platform-tools-common). Then unplug and replug. Android's guide to running apps on a device covers the details.
adb devices
If the phone shows as unauthorized, unlock it and accept the Allow USB debugging? prompt.