Troubleshooting

Common issues and solutions when working with the starter app.

Backend Issues

Database Connection Errors

Problem: Connection refused or database does not exist errors

Solutions:

1. Check if PostgreSQL is running:

   docker-compose -p starter-app -f common/docker/docker-compose.yml postgres ps

2. Restart the database:

   docker-compose -p starter-app -f common/docker/docker-compose.yml down postgres
   docker-compose -p starter-app -f common/docker/docker-compose.yml up postgres -d

3. Verify environment variables:

   DB_TYPE=remote
   DB_USER=xxx
   DB_NAME=xxx
   DB_HOST=xxx
   DB_PORT=xxx
   DB_PASSWORD=xxx

Migration Errors

Problem: Target database is not up to date or migration conflicts

Solutions:

1. Check current migration state:

   cd common
   uv run alembic current
   uv run alembic history

2. Reset migrations (development only):

   # WARNING: This will delete all data
   cd common
   uv run alembic downgrade base
   uv run alembic upgrade head

3. Fix merge conflicts in migrations:

   # Delete conflicting migration files
   rm common/alembic/versions/conflicting_migration.py
   
   # Generate a new clean migration
   uvx invoke create-migration "Merge migration conflicts"
   uvx invoke update-db

API Endpoint Not Found

Problem: 404 errors when calling API endpoints

Solutions:

1. Verify router is registered:

   # In apps/backend/src/main.py, ensure your router is included:
   from routers import your_router
   app.include_router(your_router.router)

2. Check endpoint URL:

   # Visit http://localhost:8000/docs to see all available endpoints

Frontend Issues

Type Generation Errors

Problem: TypeScript errors about missing API types

Solutions:

1. Regenerate API types:

   # Make sure backend is running first
   cd apps/frontend
   npm run codegen

2. Check backend is accessible:

   curl http://localhost:8000/openapi.json

State Management Issues

Problem: Zustand store not updating or state not persisting

Solutions:

1. Check store subscription:

   // Make sure you're using the store correctly
   const { data, setData } = useMyStore()  // ✅ Subscribes to changes
   const store = useMyStore.getState()     // ❌ Doesn't subscribe

2. Verify store updates:

   // Store updates must be immutable
   set((state) => ({
     items: [...state.items, newItem]      // ✅ Creates new array
   }))
   
   set((state) => {
     state.items.push(newItem)             // ❌ Mutates existing array
     return state
   })

3. Check DevTools:

   // Make sure devtools middleware is enabled
   export const useMyStore = create<State>()(
     devtools((set) => ({ /* ... */ }))
   )

Development Environment Issues

Port Already in Use

Problem: EADDRINUSE: address already in use :::8000

Solutions:

1. Find and kill the process:

   # Find what's using the port
   lsof -i :8000
   
   # Kill the process
   kill -9 <PID>

Performance Issues

Slow API Responses

Problem: Backend responses are taking too long

Solutions:

1. Check database queries:

   # Add database query logging in development and check the execution plan in PG (EXPLAIN ANALYSE [your query])
   # In common/src/common/services/database_service.py
   self._engine = create_async_engine(self._get_database_url(async_url=True), echo=True)
   
   # ...Or log a particular query
   query = select(...)
   print(query)
   
   # Look for N+1 queries and missing indexes

2. Add database indexes:

   # In your models, add indexes to frequently queried fields
   class Task(TaskBase, table=True):
       user_id: UUID = Field(foreign_key="user.id", index=True)
       status: str = Field(index=True)  # If you filter by status often

3. Use database query optimization:

   # Use joinedload for related data to eager load relations
   result = await db.exec(
       select(Task).options(joinedload(Task.user))
   )