Debugging Guide — Common Errors & Fixes

A reference for errors you'll encounter in this project.

Backend Errors

ModuleNotFoundError: No module named 'flask'

Cause: Dependencies not installed or venv not activated. Fix:

source venv/bin/activate    # Activate first
pip install -r app/requirements.txt

sqlite3.OperationalError: no such table: message

Cause: Database tables haven't been created yet. Fix: In Python shell:

from app import db
db.create_all()

flask_sqlalchemy or flask_cors import error

Cause: Package not installed. Fix:

pip install flask-sqlalchemy flask-cors python-dotenv openai

Port 5000 already in use

Cause: Another process is using port 5000. Fix:

# Linux/macOS
kill $(lsof -t -i:5000)

# Windows (PowerShell)
netstat -ano | findstr :5000
taskkill /PID <PID> /F

openai.AuthenticationError

Cause: Invalid or missing API key in .env. Fix: Check backend/app/.env exists and contains:

OPENAI_API_KEY=sk-...

Never share this key or commit it to git.

openai.RateLimitError

Cause: You've exceeded your API rate limit or quota. Fix: Wait a minute and retry. Check your usage at platform.openai.com.

requests.exceptions.ConnectionError

Cause: Flask server isn't running. Fix: Start the server in another terminal:

python app/__init__.py

AttributeError: 'NoneType' object has no attribute 'something'

Cause: A function returned None when you expected a value. Usually a failed database query or missing request body. Fix: Add a check:

if result is None:
    return {"error": "Not found"}, 404

Mobile Errors

Network request failed (on Android emulator)

Cause: Android emulator uses 10.0.2.2 for host machine, not localhost. Fix: In App.tsx, set:

const API_BASE_URL = 'http://10.0.2.2:5000';

Network request failed (on physical device)

Cause: Phone can't reach your computer. Fix: Use your computer's local IP (not localhost):

# Find your IP
ip addr show | grep inet    # Linux
ifconfig                     # macOS
ipconfig                     # Windows

Then update API_BASE_URL and ensure both devices are on the same WiFi.

CORS error in logs

Access to fetch at 'http://localhost:5000' from origin 'http://localhost:8081' has been blocked by CORS policy

Cause: Flask server doesn't allow cross-origin requests from the Expo dev server. Fix: Ensure flask-cors is installed and configured (see backend/step-06.md).

TypeError: undefined is not an object

Cause: You tried to access a property on undefined or null. Fix: Check if the variable exists before accessing it:

if (data && data.messages) {
    // safe to access data.messages
}

Can't find variable: fetch

Cause: You're using an older JavaScript runtime that doesn't have fetch. Fix: Install react-native-fetch-api or upgrade Expo SDK. Expo Go includes fetch.

Module "fs" has been externalized for browser compatibility

Cause: You tried to use Node.js fs module in a React Native app. Fix: React Native doesn't have fs. Read files differently or use AsyncStorage.

Git Errors

fatal: not a git repository

Cause: You're in a folder that isn't initialized with git. Fix: Run git init first.

fatal: remote origin already exists

Cause: You already added a remote. Fix: Update it instead:

git remote set-url origin https://github.com/user/repo.git

CONFLICT (content): Merge conflict in file.py

Cause: Two branches changed the same line. Fix: Open the file — look for <<<<<<<, =======, >>>>>>> markers, edit to keep the correct version, then:

git add file.py
git commit -m "Resolve merge conflict"

Still Stuck?

  1. Google the exact error message — Someone has almost certainly had the same problem
  2. Check Stack Overflow — Search with the error + your tech (e.g., "Flask sqlalchemy no such table")
  3. Ask an AI — Paste the full error and relevant code into ChatGPT or Claude
  4. Ask a friend — Explain the problem out loud (this alone often reveals the answer)
← Virtual Env