Troubleshooting

Common error codes, PATH configuration issues, and session recovery steps.

CLI Not Found & PATH Resolution

If Orbit displays an "Antigravity binary not found" error banner:

Check whether agy is runnable in your system terminal by running which agy.
If agy is located in a user-specific folder that graphical desktop environments do not include in their PATH (common on macOS GUI apps), start Orbit with an explicit variable:
export ORBIT_AGY_PATH="$(which agy)" && orbit
Alternatively, symlink your agy binary to /usr/local/bin/agy or ~/.local/bin/agy.

When Antigravity credentials expire, spawned turns may fail with an authentication error:

# Run official Antigravity login in your terminal

$ agy auth login

Authentication credentials successfully renewed.

You do not need to restart Orbit after re-authenticating. The next turn will immediately read the refreshed credentials from your local environment.

If a turn freezes due to a runaway subagent or stuck child process:

Click the red Cancel button in Orbit's status bar to dispatch a process-tree termination signal.
If an external process remains open in the background, terminate lingering instances:
pkill -f "agy"
Your conversation database and prior turns remain completely intact.