Google Antigravity Errors: Troubleshooting Guide

Google Antigravity is a powerful agent-first IDE, but because it relies on autonomous AI to navigate your file system and execute terminal commands, it can run into highly specific errors that you won't see in traditional coding assistants like Cursor or Copilot.

This guide categorizes the exact errors you will see in the Antigravity Agent Manager and terminal, why they happen, and the step-by-step fixes to get your agent back on track.

1. Workspace & File System Errors

These errors occur when the agent loses track of where it is allowed to read and write files on your Mac.

• The Cause: You have a mismatch between the project you are asking the agent to build and the workspace folder you have selected in the left sidebar. The agent has strict sandboxing rules and will crash if it tries to modify files outside its designated folder.
• The Fix: Look at the Workspaces tab in the left sidebar. Click "Change Workspace" and select the exact folder where your project lives. Once aligned, restart the task.

• The Cause: The file the agent is trying to modify is locked by another process on your Mac. Usually, this means you have a local development server (like Vite or Next.js) currently running in the background holding the file hostage.
• The Fix: Go to the Terminal view in Antigravity, press Ctrl + C to kill the running dev server, and then type "Retry" in the agent chat.

2. Model & Connection Errors

Because Antigravity relies heavily on cloud LLMs (like Gemini 3 and Claude), you will occasionally hit server-side bottlenecks.

• The Cause: This happens almost exclusively when using Claude Sonnet or Claude Opus during peak usage hours. The API rate limits reject the agent's request.
• The Fix: Do not rewrite your prompt. Simply click the model selector dropdown at the top of the chat, switch to Gemini 3 Flash, and click the retry icon. Gemini is much more resilient during peak hours.

• The Cause: You have kept a single agent conversation running for too long, and it has read too many files. When the context window fills up, the agent begins to "forget" your original instructions.
• The Fix: Treat agent conversations as disposable. When you see this warning, click "New Conversation". Start your prompt with: "Read the existing files in the workspace. Our goal is to..."

3. Terminal Execution Hangs

• The Cause: The agent ran a command in the terminal that requires a human to type "y/n" or select an option with arrow keys (like standard CLI setup wizards). The agent cannot press keys, so the terminal hangs until it times out.
• The Fix: You must instruct the agent to use non-interactive flags. For example, explicitly tell the agent: "Run the setup command using the -y flag so it doesn't ask for prompts."

4. Authentication Errors

• The Cause: You are trying to log into the Antigravity desktop app using a company or business Gmail address.
• The Fix: Sign out and authenticate using a standard personal @gmail.com address. Google Workspace integration is slated for the v2.0 release.

5. Agent Not Responding to Prompts

• The Cause: This is due to some internal error that freezes the prompt input.
• The Fix (Mac/iOS app): Press Command + Shift + P, in that type developer: reload window, and run that command.
• The Fix (Windows app): Press Ctrl + Shift + P (or Command + Shift + P), in that type developer: reload window, and run that command.

Once it is done, your entire Antigravity IDE will be refreshed, and hope it will start working again.

6. "Version No Longer Supported" Error

• The Cause: Google enforces a minimum version requirement server-side. Your client is outdated, or a cached state is preventing the update from applying properly.
• The Fix (General): Download the latest installer from antigravity.google/download and run it without uninstalling first.
• The Fix (Mac cache issue): Go to ~/Library/Caches/ and delete any Antigravity-related folders. Then reinstall.
• The Fix (Linux cache issue): Force a cache refresh by deleting /var/cache/apt/pkgcache.bin and running sudo apt update && sudo apt install --reinstall google-antigravity.

7. Agent Stuck on "Generating..." Indefinitely

• The Cause: The agent is waiting for a terminal command approval, the browser sub-agent is waiting for a page to load, or the model is under heavy load (usually during US peak hours).
• The Fix: Check for pending approval prompts. If none, switch to Gemini 3 Flash. To prevent this entirely, go to Settings > Terminal Execution Policy and set it to "Auto" so the agent can run safe commands without your approval.

8. Login Loop After Installing on Windows

• The Cause: Chrome is not set as the default browser, or Antigravity was installed to a custom folder path instead of the default C:\Program Files.
• The Fix: Set Chrome as your default browser in Windows Settings. Uninstall Antigravity and reinstall it exactly to C:\Program Files\Google Antigravity. Clear browser cookies before signing in again.

9. Model Context Protocol (MCP) Server Failures

• The Cause: If you're using custom integrations (like connecting to local databases or external APIs via MCP), the .agents/mcp_config.json file might have an incorrect path, or the environment lacks the required dependencies.
• The Fix: Verify the paths in your mcp_config.json. If it's a Python server, ensure you've run pip install for the required packages in that exact directory.

10. Custom Skills or Rules Not Loading

• The Cause: The .agents directory is not located at the root of your active workspace, or your SKILL.md file has invalid YAML frontmatter at the top.
• The Fix: Ensure the folder you opened in the left sidebar is the exact folder containing .agents/. Open your SKILL.md and ensure the --- blocks are perfectly formatted without trailing spaces.

11. File Edit Lock / Sync Conflicts

• The Cause: You are manually typing in a file (like an artifact or code file) inside an external editor at the exact same time the Antigravity agent is trying to apply an edit.
• The Fix: Avoid typing in files while the agent's status says "Generating...". If a conflict happens, reload the window (Cmd/Ctrl + Shift + P -> developer: reload window) and tell the agent to re-read the file before attempting the edit again.

12. Unsupported File Type Error

• The Cause: Antigravity's built-in file editing tools are optimized for plain text code files and explicitly block direct edits to structured binary/JSON formats like Jupyter Notebooks (.ipynb) to prevent corrupting them.
• The Fix: Instruct the agent to either write a Python script (.py) instead, or ask it to write a temporary python script to programmatically modify the .ipynb file for you.

13. High Memory Usage & UI Sluggishness

• The Cause: You have too many background tasks running, or your current conversation has spanned hundreds of turns, bloating the memory with huge context transcripts and multiple browser sub-agent recordings.
• The Fix: Treat long conversations as disposable. Once a feature is built, click "New Conversation" to start fresh and clear the memory.

14. Sub-Agent / Browser Tool Failures

• The Cause: The agent tries to use its browser_subagent tool to navigate a webpage, but the underlying headless browser dependencies (like Playwright) are missing or blocked by your firewall.
• The Fix: Open the terminal and run npx playwright install to download the required browser binaries for the agent.

15. "Agent terminated due to error"

• The Cause: This is a generic fallback error when the agent's backend process crashes unexpectedly. This is often caused by an API timeout from the AI model, an overloaded server during peak hours, or a malformed request.
• The Fix: First, click the blue Retry button. If it fails again immediately, click Copy debug info to see the exact API failure code (e.g., 503 or 429). The most reliable fix is to switch your active model to Gemini 3.1 Pro (High) or Gemini Flash using the model dropdown and retry the prompt, as they are often more resilient during heavy load.

16. Network Issue Connecting to Server

• The Cause: The connection between your local Antigravity IDE and the cloud AI models was abruptly interrupted. This commonly happens if your Wi-Fi drops, you switch networks (e.g., from home Wi-Fi to a mobile hotspot), or if a VPN intercepts/blocks the IDE's connection.
• The Fix: First, verify your internet connection is active. If your Wi-Fi or hotspot is working but the error persists, the IDE's internal websocket connection may be stuck in a disconnected state. Press Cmd/Ctrl + Shift + P and type developer: reload window to refresh the IDE and re-establish the connection.

Back to Basics: Setup Guide

If you're still struggling with your initial setup, make sure you've followed the core installation steps properly. It prevents 90% of the errors listed above.