Troubleshooting Guide Contents
Diagnose the Antigravity Error Before Changing Anything
The phrase Antigravity not working can mean several different failures. Some are cloud-side model or account issues; others are local shell, installer, update, proxy, or MCP configuration issues. Treat the exact error text as the starting point. A generic reinstall wastes time when the real cause is a blocked API endpoint, a missing Node.js binary, or a workspace-specific MCP crash.
Start by copying the visible error message and checking where it appears. A launch failure usually points to the installer, operating system, or security tools. A sign-in loop points to account cookies, browser handoff, clock time, or network policy. Agent execution errors often involve model availability, quota, connection stability, MCP tools, or oversized context. Terminal errors usually involve PATH inheritance, Node.js, npx, npm, or shell policy.
| Symptom | Likely cause | First fix |
|---|---|---|
| Agent execution terminated due to error | Temporary model route failure, account state, network instability, MCP crash, or context limit. | Restart the agent service, switch to a small test prompt in a clean workspace, then disable MCP servers only if the clean prompt works. |
| Model API cannot be reached | Firewall, proxy, DNS, unsupported location, expired sign-in, or service-side availability. | Confirm sign-in, test another network, allow Google AI endpoints, and retry after a short wait before changing project files. |
| exec: "npx": executable file not found in PATH | Antigravity was launched with a different environment than your terminal or Node.js is not installed. | Install Node.js LTS, verify npx in a normal terminal, then launch Antigravity from the same shell or fix the system PATH. |
| PowerShell execution policy is blocking npx | Windows policy prevents npm shim scripts from running. | Use a trusted Node.js install, adjust the user execution policy only if your organization allows it, or configure the MCP command to use cmd-safe invocation. |
| Installer opens but Antigravity still will not launch | Wrong architecture, old process, unsupported OS, security software, or damaged install directory. | Check system requirements, close every Antigravity process, install the correct x64, ARM64, Apple Silicon, Intel, apt, or dnf build. |
Quick Fixes That Solve the Most Common Failures
Update first when the app opens but behaves strangely. Antigravity depends on cloud features, so an older desktop build can open normally while agent requests, completion, or sign-in fail. Use the latest version page, then reopen the app from the normal system launcher and check the About dialog. If the old version remains, you probably have a stale shortcut or a second installation.
Restart the agent service before changing settings. Use the command palette if the UI is responsive, close background Antigravity processes if it is not, then try a short prompt in an empty or small repository. A clean prompt helps you tell the difference between a general service problem and a workspace-specific tool or context problem.
Check the network path when the message mentions a model API, unsupported location, timeout, or high traffic. Disable unstable VPN hops, confirm your proxy policy, and try a different network only for diagnosis. If another network works, the app installation is probably fine and the fix belongs in firewall, DNS, proxy, or account access rather than in the project.
Step-by-Step Antigravity Recovery Workflow
Record the exact error and version
Open the About dialog if the app launches, record the installed version, and copy the exact error text. Do this before reinstalling so you can tell whether the fix changed anything.
Test a clean workspace
Create or open a small folder with one file and run a tiny agent prompt. If the clean workspace fails, focus on account, network, app version, or global toolchain issues. If it works, inspect the original repository.
Repair the matching layer
Update the app for version problems, fix PATH or Node.js for npx problems, adjust approved shell policy for PowerShell blocks, and disable suspicious MCP servers for repository-specific agent crashes.
Error-Specific Fix Paths
Use the section that matches the error text instead of applying every fix. This reduces the chance of damaging a working configuration while trying to solve a temporary outage.
Fix agent execution terminated due to error
Create a small test folder, open it in Antigravity, and ask the agent to read a single file or explain a tiny snippet. If the clean test fails too, refresh sign-in, restart Antigravity, switch models if available, and retry later. If the clean test works but your real repository fails, inspect MCP servers, very large files, workspace rules, broken git metadata, and prompts that attach too much context.
Fix npx executable file not found in PATH
Install Node.js LTS from a trusted source, then open a new terminal and run node -v, npm -v, and npx -v. If those commands work in the terminal but fail inside Antigravity, the app inherited a different PATH. Launch it from the terminal once, or add the Node.js directory to the user or system PATH and fully restart the app.
Fix PowerShell execution policy blocks
On Windows, npm and npx may call PowerShell scripts that your policy blocks. Avoid downloading random fix scripts. If you control the machine, set a user-level policy approved by your organization or configure the relevant MCP command to run through cmd with the executable path. Corporate machines should use IT-approved policy changes.
Fix sign-in loops and model API failures
Check your system clock, default browser, cookies, and account session. Sign out and back in, then test a small request. If the error mentions location, quota, or high traffic, reinstalling usually will not help. Try again later or verify whether your network and account are allowed to reach the model provider.
Fix install and update failures
Match the installer to your platform: Windows x64 or ARM64, macOS Apple Silicon or Intel, and repository packages on supported Linux distributions. Close old processes, remove stale shortcuts, and verify that the About dialog shows the new version after installation. Use old versions only for temporary rollback testing.
App and version layer
Use this layer when the app will not launch, the About dialog shows an old build, or the UI warns that the current version is unsupported. Close all running processes, update to the latest stable version, and remove stale shortcuts only after the new build opens.
Agent and model layer
Use this layer when prompts fail with agent execution, model API, quota, high traffic, or location messages. A clean test prompt and a second network tell you whether the failure is local, account-specific, workspace-specific, or temporary service behavior.
Terminal, Node.js and MCP layer
Use this layer when the error mentions npx, node, npm, executable file not found, PATH, MCP, or PowerShell policy. Verify the commands in an external terminal, then make Antigravity inherit the same environment before editing MCP configuration.
How to Prevent Antigravity From Breaking Again
Keep the IDE, Node.js, package managers, and shell environment aligned. Many Antigravity problems appear after installing Node.js in one terminal profile while launching the IDE from a desktop icon that does not inherit the same PATH. After changing development tools, restart the whole app and confirm the integrated terminal sees the same versions as your normal terminal.
Treat MCP servers as production dependencies. Pin versions when stability matters, avoid adding multiple experimental servers at once, and keep a minimal workspace where you can test whether the base agent works. When an agent error appears only in one repository, disable recently added MCP tools or workspace rules before reinstalling the editor.
Use version control and backup project settings. Troubleshooting should never require deleting a repository or workspace folder. If you need to clear caches or remove an old install, first confirm that code, credentials, and local configuration are backed up or reproducible.
Safety note
Do not run copied PowerShell, curl, or shell commands from random pages unless you understand exactly what they do. Troubleshooting an IDE should not require granting unknown scripts access to your code, tokens, or browser session.
Useful Official and Internal Links
Use these pages to verify the installer, compatibility, and update path after you identify the failure category.
- Official Antigravity download page - Google's official installer destination
- Official Antigravity CLI troubleshooting - official CLI and command-line troubleshooting reference
- Latest Antigravity version - use this when the issue is an outdated or unsupported client
- Antigravity system requirements - check OS, architecture, RAM, storage, and network readiness
- Antigravity update guide - fix out-of-date warnings and stale old-version shortcuts