Common Issues

Build Failures

TypeScript Errors During Build

Symptom: Build fails with TypeScript errors despite ignoreBuildErrors: true. Cause: While the Next.js config ignores build errors, Vercel may still fail if there are critical type issues.

Solution: Run Type Check Locally

npm run typecheck

This runs tsc --noEmit to check for type errors without emitting files.Fix any critical errors, especially:

Missing return types in API routes
Incorrect prop types in components
Invalid module imports

Solution: Check Next.js Config

Verify your next.config.ts includes:

next.config.ts

const nextConfig: NextConfig = {
  typescript: {
    ignoreBuildErrors: true,
  },
  eslint: {
    ignoreDuringBuilds: true,
  },
};

Dependency Installation Failures

Symptom: npm install fails during Vercel deployment. Common causes:

# Delete and regenerate package-lock.json
rm package-lock.json
npm install
git add package-lock.json
git commit -m "Regenerate package-lock.json"
git push

Argument Cartographer requires Node.js 18+ due to Next.js 15 and modern ES modules.

Build Timeout on Vercel

Symptom: Build exceeds Vercel’s time limit (45 minutes on Hobby, configurable on Pro). Solutions:

Optimize build process:

package.json

"scripts": {
  "build": "NODE_ENV=production next build"
}

Check for slow dependencies:
```
npm install --timing
```
Upgrade to Vercel Pro if your project legitimately requires longer build times.

Authentication Issues

Firebase Authentication Not Initializing

Symptom: Users can’t sign in, or see “Firebase not initialized” errors.

Verify Environment Variables

Check all NEXT_PUBLIC_FIREBASE_* variables are set in Vercel:

# Required variables:
NEXT_PUBLIC_FIREBASE_API_KEY
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN
NEXT_PUBLIC_FIREBASE_PROJECT_ID
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID
NEXT_PUBLIC_FIREBASE_APP_ID

Variables without NEXT_PUBLIC_ prefix are not accessible in client-side code.

Check Authorized Domains

In Firebase Console:

Go to Authentication → Settings → Authorized domains
Add your Vercel domain (e.g., your-app.vercel.app)
Add custom domain if applicable

Verify Firebase Config Format

The config must match Firebase Console exactly:

src/firebase/config.ts

export const firebaseConfig = {
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
};

Permission Denied Errors

Symptom: Missing or insufficient permissions when accessing Firestore. The application implements strict security rules. The custom error handler provides detailed debugging:

// Error includes full request context
FirestorePermissionError: Missing or insufficient permissions
{
  "auth": {
    "uid": "user123",
    "token": {...}
  },
  "method": "get",
  "path": "/databases/(default)/documents/users/user456/argumentMaps/map1"
}

User ID Mismatch

Problem: User trying to access another user’s data.In the example above, auth.uid is user123 but the path contains user456.Solution: Ensure all Firestore paths use the authenticated user’s UID:

// ✅ Correct
const userId = auth.currentUser?.uid;
const docRef = doc(db, `users/${userId}/argumentMaps/${mapId}`);

// ❌ Incorrect
const docRef = doc(db, `users/hardcoded-id/argumentMaps/${mapId}`);

Missing userId Field

Problem: Document doesn’t have required userId field on creation.Security rules validate:

function isCreatingOwnSubcollectionDoc(userId) {
  return request.resource.data.userId == userId;
}

Solution: Include userId in all documents:

await setDoc(docRef, {
  userId: auth.currentUser.uid,  // Required!
  // ... other fields
});

Not Authenticated

Problem: User is not signed in.The error will show "auth": null.Solution: Ensure user is authenticated before accessing Firestore:

const auth = getAuth();
if (!auth.currentUser) {
  // Redirect to login or show sign-in prompt
  throw new Error('User must be authenticated');
}

API Integration Issues

Firecrawl API Failures

Symptom: Analysis fails with “Firecrawl API key not configured” or “Web Search failed”.

Verify API Key

Check the environment variable:

# Must not be placeholder
FIRECRAWL_API_KEY=fc-your-actual-key-here

The application validates:

if (!firecrawlKey || firecrawlKey === 'YOUR_API_KEY_HERE') {
  throw new Error('Firecrawl API key not configured');
}

Check API Credits

Firecrawl has usage limits. Log in to Firecrawl Dashboard to check:

Remaining credits
Rate limit status
Recent API calls

Monitor Fallback Behavior

The application has built-in fallbacks when Firecrawl fails:

// From generate-argument-blueprint.ts
if (scrapedDocs.length > 0) {
  // Use scraped content
} else if (searchResults.length > 0) {
  // Fallback 1: Use search snippets
  console.warn("Scraping failed. Using search snippets.");
} else {
  // Fallback 2: Limited analysis mode
  console.warn("No external sources available (API credits may be depleted).");
  isLimitedAnalysis = true;
}

Check Vercel logs for these warnings to understand which fallback was triggered.

Twitter API Errors

Symptom: Social Pulse feature returns empty or fails with 401/403 errors.

Invalid Bearer Token

Error: Twitter API request failed with status 401Solution:

Verify token in Twitter Developer Portal
Regenerate bearer token if expired
Update TWITTER_BEARER_TOKEN in Vercel environment variables
Redeploy application

Rate Limit Exceeded

Error: Twitter API request failed with status 429Twitter API v2 rate limits:

Basic tier: 500,000 tweets/month
Search endpoint: 180 requests per 15 minutes

Solution:

Wait for rate limit reset (check x-rate-limit-reset header)
Upgrade Twitter API tier
Implement caching for frequently searched topics

Non-Fatal Failures

Twitter failures are non-fatal by design:

try {
  const twitterResult = await twitterSearch({ query: searchQuery });
  // Process tweets...
} catch (error: any) {
  console.error("Twitter search failed, continuing. Error:", error.message);
  // Application continues without social pulse data
}

The analysis completes successfully with empty tweets array and no socialPulse summary.

Google Gemini API Issues

Symptom: Analysis fails with “AI failed to generate” errors.

Verify API Key

GOOGLE_GENAI_API_KEY=AIzaSy...

Get your key from Google AI Studio.

Check API Quotas

Gemini API has rate limits:

Free tier: 15 requests per minute
Paid tier: Higher limits based on plan

Monitor usage in Google Cloud Console.

Review Error Messages

Common errors:Safety filters triggered:

The AI model refused to respond due to safety filters.

Solution: Rephrase input query to avoid triggering content filters.Token limit exceeded:

Input tokens exceed maximum context length.

Solution: The app limits scraped content to 20,000 chars per source. If still failing, reduce number of sources.

Runtime Errors

JSON Parsing Failures

Symptom: “Failed to parse JSON from AI response” errors. The application uses JSON5 for lenient parsing, but AI responses sometimes have malformed JSON.

Diagnosis

Check Vercel logs for:

Failed to parse JSON from AI response. Raw Text: {...}

This logs the actual AI response for debugging.

Common Causes

AI returned text instead of JSON:
- AI didn’t wrap response in ```json code block
- Response is markdown or natural language
Malformed JSON:
- Trailing commas
- Single quotes instead of double quotes
- Unescaped special characters
Response truncated:
- AI hit token limit mid-response
- Network error during streaming

Recovery Strategy

The app attempts multiple parsing strategies:

// 1. Try to extract JSON from code block
const jsonBlockMatch = rawText.match(/```json\n([\s\S]*?)\n```/);

// 2. Fallback: Find first { to last }
const firstBrace = rawText.indexOf('{');
const lastBrace = rawText.lastIndexOf('}');
jsonString = rawText.substring(firstBrace, lastBrace + 1);

// 3. Use JSON5 for lenient parsing
coreAnalysis = JSON5.parse(jsonString);

If all fail, the error is thrown with the raw text for debugging.

Missing or Invalid Credibility Score

Symptom: Credibility score is 0, NaN, or outside 1-10 range. The application automatically fixes this:

// From generate-argument-blueprint.ts:299-309
if (typeof coreAnalysis.credibilityScore === 'number') {
  if (coreAnalysis.credibilityScore < 1) {
    // AI returned decimal (e.g., 0.9), convert to 1-10 scale
    coreAnalysis.credibilityScore = Math.round(coreAnalysis.credibilityScore * 10);
  }
  // Clamp to valid range
  coreAnalysis.credibilityScore = Math.max(1, Math.min(10, Math.round(coreAnalysis.credibilityScore)));
} else {
  coreAnalysis.credibilityScore = 5; // Default fallback
}

If you still see invalid scores, the AI response may not include a credibilityScore field at all.

Null Source URIs

Symptom: Argument nodes have source: "null" instead of valid URLs. Automatic fix applied:

// From generate-argument-blueprint.ts:312-322
coreAnalysis.blueprint = coreAnalysis.blueprint.map((node: any) => {
  if (!node.source || node.source === 'null' || node.source.toLowerCase() === 'null') {
    node.source = 'https://user-input.local/query'; // Placeholder
  }
  if (!node.parentId || node.parentId === 'null') {
    node.parentId = null;
  }
  return node;
});

This ensures Zod validation passes for thesis nodes that don’t have external sources.

Performance Issues

See the dedicated Performance Troubleshooting guide for:

Slow analysis generation
High API costs
Firestore optimization
Caching strategies

Getting Help

Check Vercel Logs

Vercel Dashboard → Deployments → Select deployment → Function logsLook for:

Error stack traces
Console warnings
Performance metrics

Enable Debug Logging

The application includes extensive console logging:

console.log(`[Flow] Generated Query: "${searchQuery}"`);
console.log(`[WebSearch] Found ${results.length} results`);
console.log(`[BatchScrape] COMPLETED: ${results.length}/${urls.length}`);

These help trace the exact point of failure.

Test Locally

Reproduce the issue locally:

npm run dev

Check terminal output for detailed error messages not visible in production.

Review Firebase Rules

Test security rules in Firebase Console:Firestore Database → Rules → Rules Playground

Next Steps

API Errors

Detailed API error troubleshooting

Performance

Optimize application performance

Environment Variables

Review configuration requirements

Firebase Setup

Verify Firebase configuration

Deployment Guide

Troubleshooting

Build Failures

TypeScript Errors During Build

Dependency Installation Failures

Build Timeout on Vercel

Authentication Issues

Firebase Authentication Not Initializing

Permission Denied Errors

API Integration Issues

Firecrawl API Failures

Twitter API Errors

Google Gemini API Issues

Runtime Errors

JSON Parsing Failures

Missing or Invalid Credibility Score

Null Source URIs

Performance Issues

Getting Help

Next Steps

API Errors

Performance

Environment Variables

Firebase Setup

Build docs developers (and LLMs) love

Deployment Guide

Troubleshooting

​Build Failures

​TypeScript Errors During Build

​Dependency Installation Failures

​Build Timeout on Vercel

​Authentication Issues

​Firebase Authentication Not Initializing

​Permission Denied Errors

​API Integration Issues

​Firecrawl API Failures

​Twitter API Errors

​Google Gemini API Issues

​Runtime Errors

​JSON Parsing Failures

​Missing or Invalid Credibility Score

​Null Source URIs

​Performance Issues

​Getting Help

​Next Steps

API Errors

Performance

Environment Variables

Firebase Setup

Build docs developers (and LLMs) love

Build Failures

TypeScript Errors During Build

Dependency Installation Failures

Build Timeout on Vercel

Authentication Issues

Firebase Authentication Not Initializing

Permission Denied Errors

API Integration Issues

Firecrawl API Failures

Twitter API Errors

Google Gemini API Issues

Runtime Errors

JSON Parsing Failures

Missing or Invalid Credibility Score

Null Source URIs

Performance Issues

Getting Help

Next Steps