Antigravity Won't Install or Launch: An Error-by-Error Troubleshooting Guide

Getting stuck during installation or first-time setup is one of the most frustrating experiences when trying a new tool. If Antigravity isn't installing correctly, fails on launch, or won't authenticate, this guide walks through the most common causes and their solutions.

Before You Start: Check the Requirements

It's worth confirming you meet the basic requirements before diving into troubleshooting:

Supported OS:

• macOS 12 (Monterey) or later
• Windows 10 / 11 (64-bit)
• Linux (Ubuntu 20.04+ / Debian-based)

Required:

• Node.js 18 or higher (Node 20.x LTS or 22.x recommended)
• Stable internet connection
• An Antigravity account (create one at antigravity.ai)

# Check your Node.js version
node --version  # Should show v20.x.x or higher
 
# Check npm version
npm --version

Installation Errors

Error 1: EACCES / Permission Denied

What you see:

npm error EACCES: permission denied, access '/usr/local/lib/node_modules'

Cause: npm is trying to install to a system directory that requires root access.

Best fix — Use nvm (Node Version Manager) to manage Node.js. This avoids permission issues entirely:

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 
# Install and use Node 20
nvm install 20
nvm use 20
 
# Now install Antigravity
npm install -g antigravity

On Windows: Run PowerShell as Administrator and try again.

Error 2: ENOENT / Module Not Found

What you see:

Error: Cannot find module 'xxx'

Cause: Dependencies didn't install correctly.

Fix:

# Clear npm cache and reinstall
npm cache clean --force
npm install -g antigravity@latest

If that doesn't work, uninstall and reinstall cleanly:

npm uninstall -g antigravity
npm install -g antigravity

Error 3: Node.js Version Incompatibility

What you see:

Error: The engine "node" is incompatible with this module.
Expected version ">=18.0.0". Got "16.x.x"

Fix — Update Node.js:

# With nvm
nvm install 20
nvm use 20
nvm alias default 20
 
node --version  # Should now show v20.x.x

Error 4: Network / Timeout Errors

What you see:

npm error network request to https://registry.npmjs.org failed
npm error ETIMEDOUT

Cause: Firewall, proxy, or VPN blocking npm registry access.

Fix:

# Try disabling your VPN first
# If behind a corporate proxy:
npm config set proxy http://your-proxy:8080
npm config set https-proxy http://your-proxy:8080
 
# Alternative registry (if the main one is blocked):
npm config set registry https://registry.npmmirror.com
npm install -g antigravity

Error 5: SSL Certificate Error

What you see:

npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY

Cause: Corporate security software performing SSL inspection.

Temporary workaround (use with caution):

npm config set strict-ssl false
npm install -g antigravity
npm config set strict-ssl true  # Re-enable after installation

For corporate environments, it's worth talking to your IT team about getting the package installed properly.

Login and Authentication Issues

Login Command Not Working

Symptom: antigravity login runs but nothing happens, or the browser doesn't open.

What to try:

1. Make sure you have a default browser set on your system
2. Disable popup blockers in your browser
3. Open antigravity.ai directly, log in, and manually set your token:

antigravity config set token YOUR_AUTH_TOKEN

"Workspace Not Found" on Launch

Symptom: Running antigravity shows "Workspace not found."

Cause: You're not in a directory Antigravity recognizes as a project.

Fix:

# Navigate to your project directory first
cd /path/to/your/project
antigravity
 
# Or initialize a new workspace here
antigravity init

"API Quota Exceeded" Immediately on Launch

Cause: Your account's quota is exhausted, or your trial has ended.

Fix:

1. Log in to antigravity.ai and check your usage dashboard
2. Upgrade your plan, or wait for the daily quota reset

VS Code Extension Issues

If you're using Antigravity as a VS Code extension:

Extension not responding:

1. Fully restart VS Code (not just reload)
2. Disable and re-enable the extension from the Extensions panel
3. Uninstall and reinstall the extension

Updating the extension:

Extensions panel in VS Code → Search "Antigravity" → Click Update

Troubleshooting Checklist

If you're still stuck, work through this list in order:

1. Is Node.js version 18 or higher?
2. Is your internet connection working? (Check VPN and proxy settings)
3. Have you cleared the npm cache and reinstalled?
4. Does your account have remaining quota?
5. Is your auth token valid?

If you've checked all of the above and still can't get things working, the Antigravity support page and community forums are good next steps. The community is active, and there's a good chance someone has run into the same issue.

Getting the first setup right takes a little patience, but once it's running, Antigravity makes development significantly more enjoyable.