Skip to main content

FAQ

Quick answers to common questions and troubleshooting.

Getting Started Issues​

The app won't start - what should I check?​

  1. Database connection: Make sure PostgreSQL is running (docker-compose up -d in back/docker/)
  2. Environment variables: Copy back/.env.example to back/.env and fill in required values
  3. Dependencies: Run uv sync --directory back and npm install --prefix front
  4. Migrations: Run bash scripts/init_database.sh to set up the database schema

I'm getting CORS errors in the browser​

Check that your frontend is running on http://localhost:3000 and backend on http://localhost:8000. The Vite proxy is configured for these ports.

My API types aren't updating after backend changes​

# Regenerate types from the backend OpenAPI schema
cd front
npm run generate-api

Make sure your backend is running when you run this command.

Development Workflow​

How do I add a new dependency?​

Backend (Python):

cd back
uv add package-name

Frontend (Node.js):

cd front  
npm install package-name

How do I reset my database?​

# Stop and remove the database container
docker-compose -p pg-demo -f back/docker/docker-compose.yml down -v

# Start fresh and run migrations
docker-compose -p pg-demo -f back/docker/docker-compose.yml up -d
bash scripts/init_database.sh

My migrations are failing​

Common issues:

  • Conflicting migrations: Check alembic/versions/ for duplicate revision numbers
  • Model changes: Make sure your SQLModel changes match the migration
  • Database state: Try uv run alembic downgrade -1 then uv run alembic upgrade head

Feature Development​

Where should I put my new code?​

  • New API endpoints: back/src/routers/ (see Backend Tutorial)
  • New React components: front/src/components/features/ (see Frontend Tutorial)
  • Database models: back/src/models/db_models.py
  • New pages: front/src/pages/ and add route to routes.tsx

How do I debug API calls?​

  1. Check network tab in browser dev tools
  2. Use the API docs at http://localhost:8000/docs to test endpoints
  3. Check backend logs in your terminal
  4. Verify types with TypeScript compilation

My Zustand store isn't updating the UI​

Make sure you're using the store hook in your component:

// ❌ Wrong - doesn't trigger re-renders
const store = useTaskStore

// ✅ Correct - triggers re-renders when data changes  
const { tasks, loading } = useTaskStore()

Production Issues​

How do I configure environment variables?​

  1. Add to ConfigService: back/src/services/config_service.py
  2. Add to .env.example: So other developers know it's required
  3. Set in production: Through your deployment platform's environment variables

My styles look different in production​

TailwindCSS purges unused styles in production. Make sure your class names are complete strings:

// ❌ Dynamic classes might get purged
const color = 'blue'
<div className={`text-${color}-500`}>

// ✅ Complete class names are preserved  
<div className="text-blue-500">

The app is slow in production​

  1. Check bundle size: npm run build and look at the dist folder size
  2. Lazy load pages: Use React.lazy() for large pages
  3. Optimize images: Use modern formats and appropriate sizes
  4. Database queries: Check for N+1 queries in your API endpoints

Common Errors​

ModuleNotFoundError in Python​

Your Python path might be wrong. Run commands from the back/ directory:

cd back
uv run python -m src.main  # Include the src module path

TypeScript errors after API changes​

# Clean and regenerate everything
rm -rf front/node_modules/.cache
npm run generate-api --prefix front
npm run build --prefix front

"Port already in use" errors​

Find and kill the process using the port:

# Find what's using port 8000
lsof -ti:8000

# Kill the process
kill -9 $(lsof -ti:8000)

Still Need Help?​