Antigravity Won't Launch? Beginner Setup Error FAQ

Setup and context

Setting up Antigravity can sometimes result in launch failures, blank screens, or non-functional integrations. This beginner-focused FAQ article covers 7 common setup errors and their practical solutions in Q&A format.

:::info This FAQ is based on official Antigravity documentation and multiple user support cases. :::

Q1: Antigravity Won't Launch After Installation (Blank Screen)

Symptoms

• Running claude-code command produces no output
• Browser window opens but displays a blank/white screen
• No error messages in the console

Root Causes and Solutions

Cause 1: Corrupted Cache

First, try clearing your Antigravity cache:

# macOS/Linux
rm -rf ~/.cache/antigravity
rm -rf ~/.config/antigravity
 
# Windows
rmdir %APPDATA%\Antigravity /s /q

Then restart Antigravity:

claude-code

Cause 2: Node.js Version Mismatch

Antigravity requires Node.js 18.0 or higher. Check your current version:

node --version

If your version is below 18.0, upgrade to the latest LTS version. Using nvm (Node Version Manager) is recommended:

# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
 
# Install Node.js 20 LTS
nvm install 20
nvm use 20

Cause 3: Port Conflict

Antigravity uses port 5173 by default. Check if another process is using it:

# macOS/Linux
lsof -i :5173
 
# Windows (PowerShell)
netstat -ano | findstr :5173

If port 5173 is occupied, either kill that process or specify a different port:

VITE_PORT=5174 claude-code

:::tip If port 5173 keeps conflicting, check the port settings for VSCode or other development servers. :::

Q2: Firebase / Supabase Connection Errors

Symptoms

• "Cannot connect to Firebase project" error message
• Supabase database not recognized
• "Invalid credentials" error persists even after entering correct information

Root Causes and Solutions

Cause 1: Missing Environment Variables

When using Firebase or Supabase, you must configure your credentials in a .env.local file:

# Create .env.local in your project root
touch .env.local

Add the appropriate credentials to .env.local:

# For Firebase
VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
 
# For Supabase
VITE_SUPABASE_URL=https://your_project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key

Restart Antigravity after configuration:

# Stop current process (Ctrl+C), then restart
claude-code

Cause 2: Invalid or Expired API Keys

Verify that your API keys are still valid in your Firebase/Supabase console:

• Firebase: Firebase Console → Project Settings → Service Accounts
• Supabase: Supabase Dashboard → Settings → API

If keys are expired or invalid, generate new ones from your respective console.

Cause 3: CORS Configuration Missing

If you see CORS errors in the browser console (F12 → Console tab), check your Firebase/Supabase CORS settings.

For Firebase:

firebase apps:sdkconfig --json | jq '.hosting[0].origin'

Q3: Git Integration Not Working (Cannot Commit)

Symptoms

• Git repository not recognized when selected
• "Unable to find git repository" error appears
• Commit/Push buttons are grayed out

Root Causes and Solutions

Cause 1: Current Directory is Not a Git Repository

Antigravity requires the project root to contain a .git folder:

# Check if .git folder exists
ls -la | grep .git
 
# Initialize Git if not already a repository
git init

Cause 2: Git User Information Not Set

Configure your Git user information on first use:

git config user.name "Your Name"
git config user.email "your.email@example.com"
 
# To use these settings globally
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Cause 3: SSH Key Not Registered

If using SSH for GitHub/GitLab, verify your SSH key is registered:

# Check if SSH key exists
ls ~/.ssh/id_rsa*
 
# Generate SSH key if missing
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa

Add your public key (id_rsa.pub) to GitHub/GitLab settings.

Cause 4: Remote URL is Incorrect

# Check remote URL
git remote -v
 
# Correct the URL if necessary
git remote set-url origin https://github.com/username/repo.git

:::warning When using HTTPS URLs, you'll need a Personal Access Token (PAT) instead of your password. Generate one from GitHub Settings → Developer settings. :::

Q4: Extensions Not Loading (Plugin Features Unavailable)

Symptoms

• Extensions installed from Antigravity Marketplace don't appear
• No extensions are listed in the marketplace
• Installation completes but shows errors

Root Causes and Solutions

Cause 1: Extensions Directory Not Found

Antigravity stores extensions in a specific directory. Verify it exists:

# macOS/Linux
ls -la ~/.config/antigravity/extensions
 
# Windows
dir "%APPDATA%\Antigravity\extensions"

If the directory doesn't exist, create it:

# macOS/Linux
mkdir -p ~/.config/antigravity/extensions
 
# Windows (PowerShell)
New-Item -ItemType Directory -Path "$env:APPDATA\Antigravity\extensions" -Force

Cause 2: Missing Extension Dependencies

Some extensions require additional packages. Check the extension's documentation and install necessary dependencies:

# Example for Python extension
pip install -r ~/.config/antigravity/extensions/plugin-name/requirements.txt

Cause 3: Stale Cache

Extension cache may be outdated. Clear it and restart:

# Clear cache
rm -rf ~/.config/antigravity/cache
 
# Restart Antigravity
claude-code

Q5: Terminal Freezing (Unresponsive)

Symptoms

• Terminal becomes unresponsive after long-running commands
• Command output stops mid-execution
• Ctrl+C doesn't work

Root Causes and Solutions

Cause 1: Memory Exhaustion

Large builds or memory-intensive operations can cause freezing. Check your system's memory:

# macOS/Linux
top -l 1 | grep "PhysMem"
 
# Windows (PowerShell)
Get-ComputerInfo | Select-Object CsTotalPhysicalMemory, OsAvailablePhysicalMemory

If low on memory, try these solutions:

1. Close unnecessary applications
2. Close browser tabs
3. Increase Node.js heap size:

NODE_OPTIONS="--max-old-space-size=4096" claude-code

Cause 2: Infinite Loop or Deadlock

When a script freezes during execution, try interrupting with Ctrl+C multiple times:

Ctrl+C Ctrl+C Ctrl+C

If that doesn't work, force-kill the Antigravity process from another terminal:

# macOS/Linux
ps aux | grep claude-code
kill -9 <PID>
 
# Windows (PowerShell)
Get-Process | Where-Object {$_.Name -like "*claude*"} | Stop-Process -Force

Cause 3: Network Timeout

API calls or file transfers can timeout on unstable connections. Increase timeout duration:

# Edit Antigravity config file
# ~/.config/antigravity/config.json or ~/.antigravity/config.json
 
{
  "network": {
    "timeout": 60000,  // 60 seconds
    "retries": 3
  }
}

:::tip Create the config file manually if it doesn't exist and add the above configuration. :::

Q6: Cannot Open Workspace / Project Load Failure

Symptoms

• "Failed to load workspace" error displayed
• Project doesn't open when selected
• Workspace list is empty

Root Causes and Solutions

Cause 1: Invalid Project Path

Antigravity requires absolute paths, not relative paths:

# Incorrect: relative path (will fail)
claude-code ./my-project
 
# Correct: absolute path
claude-code /Users/username/path/to/my-project

Cause 2: Incorrect Project Structure

Verify your project has the required structure. At minimum:

my-project/
├── package.json
├── src/
└── .git/ (if using Git integration)

If package.json is missing, create one:

cd /path/to/my-project
npm init -y

Cause 3: Insufficient File Permissions

Check if you have read permissions for the project directory:

# Check directory permissions
ls -ld /path/to/my-project
 
# Grant permissions if needed
chmod 755 /path/to/my-project

Cause 4: Corrupted Workspace Configuration

Your Antigravity configuration may be corrupted. Reset it (backup first):

# Backup existing configuration
cp -r ~/.config/antigravity ~/.config/antigravity.backup
 
# Delete configuration
rm -rf ~/.config/antigravity
 
# Restart Antigravity to reinitialize
claude-code

Q7: Autocomplete is Slow / Not Working

Symptoms

• Autocomplete doesn't appear when typing
• Autocomplete takes several seconds to display
• Autocomplete doesn't work for specific languages

Root Causes and Solutions

Cause 1: LSP (Language Server Protocol) Not Running

Autocomplete depends on LSP. Verify it's initialized:

# Check Antigravity logs
tail -f ~/.config/antigravity/logs/app.log
 
# Look for "LSP initialized" message

If LSP isn't running, install language servers:

# JavaScript/TypeScript
npm install -g typescript typescript-language-server
 
# Python
pip install python-lsp-server
 
# Go
go install golang.org/x/tools/gopls@latest

Cause 2: Code Index Not Generated

First startup can take time as Antigravity analyzes your code. Wait a few minutes before testing autocomplete again.

Cause 3: Insufficient Memory

Large projects consume more memory for autocomplete. Increase heap size:

NODE_OPTIONS="--max-old-space-size=2048" claude-code

Cause 4: Language Configuration Issues

Verify your language is supported and properly configured:

# Edit ~/.config/antigravity/config.json
{
  "languages": {
    "javascript": { "enabled": true },
    "typescript": { "enabled": true },
    "python": { "enabled": true }
  }
}

:::info Check the official documentation for the complete list of supported languages. :::

Cause 5: Input Method Editor (IME) Conflicts

On macOS, Japanese input systems may disable autocomplete. Try this configuration:

# ~/.config/antigravity/config.json
{
  "editor": {
    "imePreeditStyle": "underline",
    "imeAutoHide": true
  }
}

Summary

Most Antigravity setup errors fall into these categories:

If issues persist after trying these solutions, contact official support at support@antigravitylab.net or reach out to the Antigravity community on Discord or GitHub Discussions.