Troubleshooting

Common issues and how to resolve them. If something isn't covered here, check the FAQ.

Setup & compatibility

The compatibility check shows a blocking issue. Your operating system or version isn't supported. Check the minimums in System requirements: macOS 12+, Windows 10 build 17763+/11, or a modern 64-bit Debian-based Linux. Update your OS and click Re-check.

The compatibility check shows a warning. Usually low RAM (under 8 GB) or few CPU cores (under 4). You can continue, but long missions will be slower. 16 GB RAM is the comfortable target.

Runtime download

The runtime download is slow or stalls. The Pro runtime is large (up to ~20 GB). The download resumes if interrupted — leave the setup screen open, or reopen it, and it continues where it left off. Ensure you have enough free disk (~25 GB) and a stable connection.

Not enough disk space. Free up space so you have about 25 GB available, then retry. See Data locations for where the runtime is stored.

macOS

"AgentRidge can't be opened" / unidentified developer. Open System Settings → Privacy & Security, find the notice for AgentRidge, and click Open Anyway, then relaunch. See the macOS install guide.

The agent can't act / permissions look denied. Confirm Accessibility and Full Disk Access are enabled for AgentRidge in System Settings → Privacy & Security, then click Check again on the Permissions step.

Windows

SmartScreen blocks the app. Click More info → Run anyway on first launch.

The installer or app asks for administrator rights. This is expected — AgentRidge installs per-machine and authorized operations can need elevation. Choose Yes. See the Windows install guide.

Linux

The AppImage won't start. Make it executable (chmod +x) and ensure FUSE is available (sudo apt install libfuse2 on Ubuntu). As a fallback, extract it with --appimage-extract and run the binary inside. See the Linux install guide.

Missing libraries on a minimal image. The .deb pulls in its dependencies via apt. On a minimal or server install you may need a desktop/GTK stack. Prefer the .deb on Ubuntu/Debian so dependencies resolve automatically.

Missions

Attacker mode won't launch. Attacker mode requires an active Pro subscription. On the free trial, run in Auditor mode, or upgrade to Pro.

The launch button is disabled. The brief isn't valid yet: you need a client name, at least one target (IP, URL, or LAN CIDR), at least one engagement case, and the authorization confirmation. See New Mission.

A mission seems stuck on one step. AgentRidge is designed to keep working even if a sub-step stalls — it documents the blocker, switches technique, and continues the rest of the scope. Watch the Activity stream to see what it's doing.

Account & licensing

My Pro features aren't showing after upgrading. Entitlement refreshes when it's next checked. Reopen the app (or the account/plan view) so it re-reads your subscription status.

Next: FAQ →