Troubleshooting

Quick solutions to common problems. If you're stuck, try these steps first.

Connectivity & Access

Agent stuck loading or 'Connection Refused'

Clear Site Data: Don't just reload. Go to DevTools (F12) → Application → Storage → Clear Site Data.
VPN/DNS: Antigravity can conflict with strict corporate VPNs. Try switching DNS to 8.8.8.8 or disabling VPN temporarily.
Mobile Hotspot: If on a restricted network (university/office), verify connection via mobile hotspot to rule out firewall blocking.

Account Lockout after Logout

Incognito Mode: If you are stuck in a logout loop, try signing in via an Incognito window.
Primary Profile: Ensure your Google Account is the primary profile in Chrome/Edge to prevent token mismatches.

'Network Timeout' or 'Failed to Connect' errors

Firewall Check: Corporate firewalls may block WebSocket connections. Contact IT to whitelist *.antigravity.google.
Proxy Settings: If behind a proxy, ensure HTTP/HTTPS proxy is configured correctly in system settings.
Check Status: Visit the official status page to rule out global outages.

'Too many requests' or rate limit errors

Free tier has quota limits. Wait 15 minutes or upgrade to Pro for higher limits.
If you're on Pro and still hitting limits, verify your billing status in Account Settings.

Security & Safety

Prevent Unauthorized Code Execution

Terminal Policy: Set "Terminal Auto Execution Policy" to "Confirm" (not Auto) in Settings.
This prevents the agent from executing shell commands without your explicit approval, mitigating risks from untrusted inputs.

Prompt Injection Risks

Markdown Rendering: Be cautious when the agent renders Markdown from untrusted sources. Malicious images/links could trigger data exfiltration.
Avoid processing third-party repositories with sensitive local files in the same workspace.

Agents & MCP Servers

Agents won't spawn or start

Run "Restart Agent Service" from the Command Palette (Ctrl+Shift+P).
Check the Output Panel (View → Output → "Antigravity Agent") for specific error codes.
On Windows, try running Antigravity as Administrator.

MCP Server Errors

Ensure valid JSON in configuration files.
Avoid keys starting with numbers (e.g., 1mcp). Rename them to start with a letter.
Disable all MCP servers and re-enable one by one to identify the culprit.

Agent crashes mid-task

Memory: If dealing with large files (>100MB), reduce Context Limit in Settings.
Logs: Check crash logs in ~/.antigravity/logs for specific error traces.

Multiple agents conflict or interfere

Run only one agent per workspace to avoid resource conflicts.
If managing multiple projects, use separate workspace folders.

Performance & Memory

High Memory Usage / Sluggishness

Limit concurrent agents to 3 or fewer.
Clear the Artifact Cache: Settings → Storage → Clear Cache.
Reduce Context Limit in Model settings if running on lower RAM (8GB or less).

UI freezes or becomes unresponsive

Force quit and restart the application.
Disable hardware acceleration: Settings → Advanced → Use Hardware Acceleration (toggle off).

Slow file indexing

Exclude large directories (e.g., node_modules, .git) via Settings → File Exclusions.
On Windows, disable antivirus real-time scanning for the workspace folder temporarily.

Model Intelligence

Hallucinations or Low Quality Results

Nano Banana Pro: Switch to this model for high-fidelity code rendering if the default model struggles with syntax.
Gemini 3 Flash: Use this for low-latency tasks where speed is prioritized over complex reasoning.
Prompt Refinement: Add explicit constraints ("Use TypeScript", "Follow ESLint rules") to reduce ambiguity.

Context limit exceeded errors

Break large tasks into smaller sub-tasks.
Use @file references instead of pasting entire files into prompts.

Model switching best practices

Use Gemini 3 Flash for quick edits and refactoring.
Use Nano Banana Pro for complex logic or debugging.
Avoid switching mid-conversation; it resets context.