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 common/docker/)
  2. Environment variables: Copy .env.example to .env (in project root) and fill in required values
  3. Dependencies: Run uvx invoke install-all to install all dependencies
  4. Storage (DB/Azurite) initialization: Run uvx invoke init-abraxas-azurite and uvx invoke update-db to set up the database schema and storage containers

I'm getting CORS errors in the browser​

Check that your frontend is running on http://localhost:3000 and backend on http://localhost:8000. Next.js is configured with the correct API proxy.

My API types aren't updating after backend changes​

# Regenerate types from the backend OpenAPI schema
cd apps/frontend
npm run codegen

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

Development Workflow​

How do I add a new dependency?​

Backend (Python):

cd apps/backend
uv add package-name

Common (Python - shared across apps):

cd common
uv add package-name

Frontend (Node.js):

cd apps/frontend
npm install package-name

How do I reset my database?​

# Stop and remove the database container
docker-compose -p starter-app -f common/docker/docker-compose.yml down postgres -v

# Start fresh and run migrations
docker-compose -p starter-app -f common/docker/docker-compose.yml up postgres -d
uvx invoke update-db

My migrations are failing​

Common issues:

  • Conflicting migrations: Check common/alembic/versions/ for duplicate revision numbers
  • Model changes: Make sure your SQLModel changes in common/src/common/models/db_models.py match the migration
  • Database state: Try cd common && uv run alembic downgrade -1 then uv run alembic upgrade head

Feature Development​

Where should I put my new code?​

  • New API endpoints: apps/backend/src/routers/ (see Backend Tutorial)
  • New React components: apps/frontend/src/components/features/ (see Frontend Tutorial)
  • Database models: common/src/common/models/db_models.py
  • Shared services: common/src/common/services/
  • New pages: apps/frontend/src/app/your-page/page.tsx (Next.js App Router)

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 = useUserStore

// ✅ Correct - triggers re-renders when data changes
const { current } = useUserStore()

Production Issues​

How do I configure environment variables?​

  1. Add to ConfigService: common/src/common/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: cd apps/frontend && npm run build and check the .next folder size
  2. Use Next.js optimizations: Server Components, Image optimization, etc.
  3. Optimize images: Use Next.js <Image> component
  4. Database queries: Check for N+1 queries in your API endpoints

Common Errors​

ModuleNotFoundError in Python​

Make sure you're using the correct invoke commands from the project root:

# From project root
uvx invoke backend  # Starts backend correctly
uvx invoke worker   # Starts worker correctly

TypeScript errors after API changes​

# Clean and regenerate everything
cd apps/frontend
rm -rf .next node_modules/.next
npm run codegen
npm run build

"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?​