Skip to main content

Troubleshooting Guide

Common issues and solutions for AI content reporpuser.

Table of Contents​

Installation Issues​

Node.js Not Found​

Problem: node: command not found

Solution:

# Download and install Node.js 18+ from nodejs.org
# Or use package manager:

# Ubuntu/Debian
sudo apt install nodejs npm

# macOS (with Homebrew)
brew install node

# Verify installation
node --version
npm --version

Flutter Not Found​

Problem: flutter: command not found

Solution:

# Add Flutter to PATH
export PATH="$PATH:/path/to/flutter/bin"

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH="$PATH:/path/to/flutter/bin"' >> ~/.bashrc

# Verify installation
flutter --version
flutter doctor

npm install Fails​

Problem: Dependency installation errors

Solutions:

# Clear cache
npm cache clean --force

# Remove old files
rm -rf node_modules package-lock.json

# Try again
npm install

# If still fails, check Node version
node --version  # Should be 18+

Flutter pub get Fails​

Problem: Flutter dependency errors

Solutions:

# Clean Flutter cache
flutter clean
flutter pub cache repair

# Try again
flutter pub get

# If still fails
rm -rf .dart_tool
flutter pub get

Backend Issues​

Port 3000 Already in Use​

Problem: Error: listen EADDRINUSE: address already in use :::3000

Solutions:

Option 1: Kill existing process

# Linux/macOS
lsof -ti:3000 | xargs kill -9

# Or find and kill manually
lsof -i :3000
kill [PID]

Option 2: Change port

# Edit backend/.env
PORT=3001

# Restart server

Cannot Find Module​

Problem: Error: Cannot find module 'express'

Solution:

cd backend
rm -rf node_modules
npm install
npm run build

TypeScript Build Errors​

Problem: Build fails with TypeScript errors

Solutions:

  1. Check TypeScript version:
npx tsc --version
# Should be 5.3+
  1. Reinstall TypeScript:
npm install -D typescript@latest
  1. Clean and rebuild:
rm -rf dist
npm run build
  1. Check for syntax errors in source files

Service Account Not Found​

Problem: Service account not configured

Solutions:

  1. If using Firebase:
# Verify file exists
ls backend/serviceAccountKey.json

# Check permissions
chmod 600 backend/serviceAccountKey.json

# Verify path in .env
cat backend/.env | grep FIREBASE
  1. If NOT using Firebase:
  • This is just a warning
  • App works without Firebase
  • History won't persist server-side

API Key Invalid​

Problem: 401 Unauthorized or Invalid API key

Solutions:

  1. Check .env file:
cat backend/.env | grep OPENAI_API_KEY
  1. Verify no extra spaces:
# Wrong:
OPENAI_API_KEY= sk-xxxxx  # space before key

# Right:
OPENAI_API_KEY=sk-xxxxx   # no space

  1. Regenerate key from OpenAI dashboard

  2. Check billing/quota status on OpenAI

  3. Test key:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

CORS Errors​

Problem: Browser shows CORS errors

Solution:

Edit backend/.env:

# For development
ALLOWED_ORIGINS=http://localhost:*,http://127.0.0.1:*

# For production
ALLOWED_ORIGINS=https://yourdomain.com

Restart backend after changing.

Frontend Issues​

Build Fails on Linux​

Problem: Missing GTK libraries

Solution:

sudo apt-get update
sudo apt-get install \
  clang \
  cmake \
  ninja-build \
  pkg-config \
  libgtk-3-dev \
  liblzma-dev \
  libblkid-dev

Build Fails on macOS​

Problem: Xcode errors

Solution:

# Install Xcode Command Line Tools
xcode-select --install

# Accept license
sudo xcodebuild -license accept

# Update CocoaPods (for iOS)
sudo gem install cocoapods

Build Fails on Windows​

Problem: Visual Studio errors

Solution:

  1. Install Visual Studio 2022
  2. Include "Desktop development with C++"
  3. Restart computer
  4. Try build again

Cannot Connect to Backend​

Problem: App shows connection error

Diagnosis:

# Test backend is running
curl http://localhost:3000/health

# Should return: {"status":"healthy"...}

Solutions:

  1. Backend not running:
cd backend
npm start
  1. Wrong URL in Settings:
  • Open app Settings
  • Set API URL to http://localhost:3000
  • Click Test Connection
  1. Firewall blocking:
  • Check firewall settings
  • Allow port 3000
  • Try localhost vs 127.0.0.1
  1. CORS issues:
  • Check backend CORS configuration
  • See CORS section above

App Crashes on Startup​

Problem: Flutter app crashes immediately

Solutions:

  1. Check Flutter doctor:
flutter doctor -v
  1. Clean and rebuild:
flutter clean
flutter pub get
flutter run
  1. Check logs:
flutter run -v  # Verbose mode
  1. Try different device:
flutter devices
flutter run -d linux  # or macos, windows

Generation Issues​

Generation Fails​

Problem: All platforms show "Failed"

Diagnose:

  1. Check backend logs
  2. Test connection in Settings
  3. Verify API key

Common Causes:

  1. API Key Issue:
# Check backend logs for:
# "API key invalid" or "401"
# → Fix API key in .env
  1. No Credits/Quota:
# Check OpenAI dashboard
# → Add billing or wait for quota reset
  1. Rate Limit:
# Backend logs show "429 Too Many Requests"
# → Wait a few minutes
# → Upgrade OpenAI plan
  1. Network Issue:
# Test internet connection
curl https://api.openai.com

# → Check firewall/proxy

Some Platforms Fail​

Problem: Mixed success (e.g., 2/3 succeed)

This is normal when:

  • Content doesn't fit platform constraints
  • AI can't adapt tone appropriately
  • Character limits too restrictive

Solutions:

  • Click regenerate on failed platforms
  • Try different tone
  • Provide more/less content
  • Check backend logs for specific error

Content Quality Issues​

Problem: Generated content not good enough

Solutions:

  1. Try different tone:
  • Professional for business
  • Casual for social
  • Formal for academic
  1. Provide more context:
  • Longer input = better results
  • Clear structure helps
  • Complete sentences work better
  1. Use regenerate button:
  • Each generation is unique
  • Try 2-3 times if needed
  1. Check AI model:
# In backend/.env
AI_MODEL=gpt-4-turbo-preview  # Better quality
# vs
AI_MODEL=gpt-3.5-turbo  # Faster, cheaper
  1. Add custom instructions:
  • Use custom instructions field
  • Be specific about requirements

Slow Generation​

Problem: Takes too long to generate

Normal times:

  • 1 platform: 3-5 seconds
  • 3 platforms: 8-12 seconds
  • 5+ platforms: 15-25 seconds

If slower:

  1. Check model:
# GPT-4 is slower but better
# GPT-3.5 is faster but simpler
AI_MODEL=gpt-3.5-turbo  # Try this
  1. Check network:
# Test speed to OpenAI
time curl -I https://api.openai.com
  1. Generate fewer platforms:
  • Select 2-3 instead of 10
  • Generate in batches
  1. Check backend load:
# CPU usage
top
# Look for node process

Firebase Issues​

Firestore Permission Denied​

Problem: PERMISSION_DENIED errors

Solution:

Since we use Firebase Admin SDK (server-side), this shouldn't happen unless:

  1. Wrong credentials:
# Verify service account file
cat backend/serviceAccountKey.json
# Should be valid JSON
  1. Wrong project:
# Check project ID matches
# .env: FIREBASE_DATABASE_URL
# serviceAccountKey: project_id field
  1. Service account lacks permissions:
  • Go to Firebase Console
  • IAM & Admin
  • Verify service account has "Editor" role

Firebase Not Saving Data​

Problem: No errors but data doesn't appear in Firestore

Diagnosis:

# Check backend logs for:
# "Skipping save generation - Firebase not initialized"
# → Firebase is disabled

Solutions:

  1. Check initialization:
# Backend logs should show:
# "Admin SDK initialized successfully"
# If not, Firebase isn't set up
  1. Verify collection names:
  • Open Firebase Console
  • Check Firestore Database
  • Should see: settings, generations, analytics
  1. Check indexes:
  • Firebase may require index for queries
  • Click link in error message to create

Firebase Connection Slow​

Problem: Saves/loads take long

Solutions:

  1. Choose closer Firebase region
  2. Check internet connection
  3. Use local caching (built-in)
  4. Consider disabling for dev:
# Comment out in .env
# FIREBASE_SERVICE_ACCOUNT_PATH=...

Performance Issues​

High Memory Usage​

Backend:

# Monitor
ps aux | grep node

# Limit if needed (in bytes)
NODE_OPTIONS="--max-old-space-size=512" npm start

Frontend:

  • Flutter desktop apps use ~200-300MB normally
  • Mobile apps use less
  • Check for memory leaks if much higher

High CPU Usage​

Normal during:

  • Generation (AI processing)
  • Build (compilation)

Not normal:

  • Idle state
  • After generation complete

Solutions:

  • Restart backend
  • Check for infinite loops in logs
  • Update to latest version

Error Messages Reference​

"Failed to fetch"​

  • Backend not running
  • Wrong URL
  • CORS issue
  • Network problem

"Network error"​

  • No internet connection
  • Backend unreachable
  • Firewall blocking

"Timeout"​

  • Request took too long
  • Backend overloaded
  • Slow internet
  • Try again

"Rate limit exceeded"​

  • Too many requests
  • Wait a few minutes
  • Upgrade API plan

"Invalid API key"​

  • Wrong key in .env
  • Extra spaces
  • Key expired
  • Check OpenAI dashboard

"Service account not configured"​

  • Firebase not set up (optional)
  • Missing serviceAccountKey.json
  • Wrong path in .env

Still Having Issues?​

Check Logs​

Backend:

cd backend
npm start
# Watch console output

Frontend:

flutter run -v
# Verbose output

Verify Environment​

# Node version
node --version  # 18+

# Flutter version
flutter --version  # 3.10+

# Dependencies
cd backend && npm list --depth=0
cd frontend && flutter pub deps

Test Components​

Backend health:

curl http://localhost:3000/health

Backend config:

curl http://localhost:3000/api/v1/config

Frontend connection:

  • Open Settings
  • Click Test Connection
  • Should show provider info

Clean Install​

If all else fails:

# Backend
cd backend
rm -rf node_modules dist package-lock.json
npm install
npm run build

# Frontend
cd frontend
flutter clean
rm -rf .dart_tool
flutter pub get
flutter run

Contact Support​

Include in report:

  • Error message (exact text)
  • Steps to reproduce
  • Backend logs
  • Frontend logs
  • Environment info:
    • OS version
    • Node version
    • Flutter version
    • .env configuration (remove API keys!)

Most issues are configuration-related. Double-check:

  • ✅ API key is valid
  • ✅ .env file exists and is correct
  • ✅ Backend is running
  • ✅ Frontend can reach backend
  • ✅ Dependencies are installed