Troubleshooting Antigravity Build and Deployment Errors

Building and deploying applications in Antigravity should be straightforward, but when things go wrong, cryptic error messages can derail your workflow. The good news: most errors follow predictable patterns and have well-established solutions.

Error Diagnosis Flowchart

When a build or deployment fails, follow this diagnostic order:

Step 1: Read the full error message
     ↓
Step 2: Check environment variables
     ↓
Step 3: Verify npm/yarn dependencies
     ↓
Step 4: Confirm Firebase configuration
     ↓
Step 5: Test network connectivity
     ↓
Step 6: Inspect browser console & Network tab

Common Errors and Solutions

Error 1: npm Dependency Conflict

Symptoms: npm install fails with messages like:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Found: react@18.2.0
npm ERR! Could not find a version that matches "react@17.0.0"

Root Cause: Your package.json specifies incompatible package versions that conflict with each other.

Solution 1: Use Legacy Peer Deps Flag

npm install --legacy-peer-deps

This flag bypasses strict dependency checking and installs packages even if versions don't perfectly match.

Solution 2: Update package.json Manually

Open package.json and align versions:

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "next": "^14.0.0",
    "firebase": "^10.0.0"
  }
}

Then clean and reinstall:

rm -rf node_modules package-lock.json
npm install

Solution 3: Switch to Yarn

Yarn often resolves dependencies better than npm:

yarn install

Error 2: Firebase Authentication Failed

Symptoms: Build or runtime error like:

Error: Authentication token failed to initialize
Cannot read property 'getAuth' of undefined

Root Cause: Firebase configuration is not properly set in environment variables.

Solution:

1. Verify .env.local File

Check that .env.local exists in your project root with the correct format:

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key_here
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

Important: After adding or changing environment variables, restart your local dev server:

# Stop current server (Ctrl+C)
# Then restart it
npm run dev

2. Verify Firebase Config in Console

Log into Firebase Console, navigate to Project Settings > Your apps, and confirm all credentials match your .env.local.

3. Check Firebase Initialization Code

Ensure your Firebase module is initialized correctly:

// lib/firebase.ts
import { initializeApp } from 'firebase/app';
 
const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
};
 
// Debug: log to confirm values aren't 'undefined'
console.log('Firebase Config loaded:', Object.keys(firebaseConfig).length === 6);
 
const app = initializeApp(firebaseConfig);
export default app;

Error 3: CORS Error (Cross-Origin Resource Sharing)

Symptoms: Browser console shows:

Access to XMLHttpRequest at 'https://api.example.com' from origin
'https://my-app.firebaseapp.com' has been blocked by CORS policy

Root Cause: An external API doesn't allow requests from your domain.

Solution 1: Request CORS Configuration from API Provider (Best)

Contact the API provider and ask them to whitelist your Firebase Hosting domain (https://your-project.web.app) in their CORS settings.

Solution 2: Proxy Through Next.js API Routes (Recommended)

Instead of calling the API directly from the browser, proxy requests through Next.js:

// app/api/external-api/route.ts
export async function GET(req: Request) {
  try {
    const response = await fetch('https://api.example.com/data', {
      headers: {
        'Authorization': `Bearer ${process.env.API_KEY}`,
        'Content-Type': 'application/json',
      },
    });
 
    if (!response.ok) throw new Error('API request failed');
    const data = await response.json();
    return Response.json(data);
  } catch (error) {
    return Response.json(
      { error: 'Failed to fetch data' },
      { status: 500 }
    );
  }
}

Call it from your client:

// components/DataFetcher.tsx
'use client';
 
import { useEffect, useState } from 'react';
 
export default function DataFetcher() {
  const [data, setData] = useState(null);
 
  useEffect(() => {
    fetch('/api/external-api')
      .then(res => res.json())
      .then(data => setData(data));
  }, []);
 
  return <div>{JSON.stringify(data)}</div>;
}

Solution 3: Temporary CORS Proxy (Not for Production)

As a last resort, use a public CORS proxy:

// ⚠️ Only for development/testing
const response = await fetch(
  'https://cors-anywhere.herokuapp.com/https://api.example.com/data'
);

Error 4: Preview Not Loading

Symptoms: The Antigravity preview panel stays blank or shows a loading spinner indefinitely.

Root Cause: JavaScript error in your code, invalid environment variables, or Firebase initialization failure.

Solution:

1. Open Browser DevTools in Preview

Press F12 while the preview is focused. Check the Console tab for red error messages.

2. Common Error Messages and Fixes

"Cannot find module 'firebase'"
→ Run: npm install firebase

"process is not defined"
→ You're using process.env without NEXT_PUBLIC_ prefix on client
→ Add NEXT_PUBLIC_ prefix or move logic to API route

"Cannot read property 'auth' of undefined"
→ Firebase isn't initialized in your component
→ Add 'use client' directive at top of file
→ Ensure firebase module is imported

"Unexpected token '<'"
→ HTML is returned instead of JSON (API error)
→ Check API endpoint and error handling

3. Verify Firebase Initialization Order

Firebase must be initialized at the module level, not inside components:

// ✅ Correct
// lib/firebase.ts (top level)
import { initializeApp } from 'firebase/app';
const app = initializeApp(firebaseConfig);
export default app;
 
// components/MyComponent.tsx (use client)
'use client';
import app from '@/lib/firebase';
import { getAuth } from 'firebase/auth';
const auth = getAuth(app);

Error 5: Agent Timeout

Symptoms: While generating code, you get "Agent timeout" or "Request timeout" error.

Root Cause: Network latency or Antigravity's backend is slow to respond.

Solution:

1. Check Network Connection

Ensure your internet connection is stable. If you're in a region with slow international connectivity, try using a VPN.

2. Simplify Your Request

Complex, long prompts take longer to process. Break requests into smaller, focused tasks:

❌ Complex request:
"Create a full user dashboard with list, search, edit, delete,
permissions management, reports, dark mode, notifications..."

✅ Simpler request:
"Create a user list table component that fetches from Firestore
and displays name, email, and action buttons."

3. Clear Browser Cache

# Chrome: Ctrl + Shift + Delete (Windows) / Cmd + Shift + Delete (Mac)
# Firefox: Ctrl + Shift + Delete

Then reload the page and try again.

4. Try a Different Browser

Sometimes timeouts are browser-specific. Try Firefox, Safari, or Edge.

Error 6: Package Version Incompatibility

Symptoms: Runtime error like:

Error: The requested module '@react-pdf/renderer' does not provide
an export named 'Document'

Root Cause: Installed package version doesn't match the code that uses it.

Solution 1: Pin to a Specific Version

Edit package.json to use an exact version:

{
  "dependencies": {
    "@react-pdf/renderer": "3.3.0"
  }
}

Then reinstall:

rm -rf node_modules package-lock.json
npm install

Solution 2: Update to Latest

npm update @react-pdf/renderer

Solution 3: Revert to Earlier Version

npm install @react-pdf/renderer@2.3.0

Solution 4: Check Documentation

Visit the package's npm page (e.g., https://www.npmjs.com/package/@react-pdf/renderer) and check the latest version and breaking changes.

Pre-Deployment Checklist

Before deploying to production, verify:

✓ npm install completed without errors
✓ npm run build succeeded
✓ All required environment variables are set in .env.local
✓ Firebase Console shows your project is active
✓ App works correctly on local dev server
✓ Browser console shows no errors or warnings
✓ External API CORS is properly configured
✓ Sensitive data (.env.local, API keys) are in .gitignore
✓ You tested on a mobile device (if applicable)

Quick Reference: Error Message Translation

Looking back

Most Antigravity errors stem from these three categories:

1. Environment & Configuration — Missing or wrong environment variables
2. Dependencies — npm conflicts or missing packages
3. Initialization Order — Firebase or library setup in the wrong place

Next time you hit an error:

1. Read the error message carefully — It usually tells you exactly what's wrong
2. Check environment variables — Missing config causes 40% of errors
3. Restart your dev server — Fixes issues after env changes
4. Check Firebase Console — Ensure your project is active and configured

For help beyond this guide, visit the Antigravity Community or check the official Firebase documentation.

Happy building! 🚀