Skip to main content

Troubleshooting Guide

Common issues and solutions for Agentification Academy.

Installation & Setup​

npm install fails​

Error: npm ERR! code ERESOLVE or dependency conflicts

Solutions:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

# Or use legacy peer deps (if above fails)
npm install --legacy-peer-deps

Python dependencies fail​

Error: ModuleNotFoundError or pip install errors

Solutions:

# Create fresh virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install requirements
pip install -r requirements.txt

# Update pip
pip install --upgrade pip

Development Server​

Port already in use​

Error: EADDRINUSE: address already in use :::5173

Solutions:

# Use different port
npm run dev -- --port 5174

# Or kill process on port
lsof -ti:5173 | xargs kill -9  # macOS/Linux
netstat -ano | findstr :5173   # Windows

Vite not finding modules​

Error: Failed to resolve module specifier or Cannot find module

Solutions:

  1. Check import paths are correct (relative vs absolute)
  2. Restart dev server: Ctrl+C, then npm run dev
  3. Clear Vite cache: rm -rf .vite

Build fails with "Could not resolve"​

Error: RollupError: Could not resolve "path/to/file"

Solutions:

  1. Verify file paths in imports match actual files
  2. Check for relative path issues after refactoring
  3. Look for typos in import statements

Database Issues​

Cannot connect to Supabase​

Error: FetchError: fetch failed or connection timeout

Solutions:

  1. Verify VITE_SUPABASE_URL is correct
  2. Check internet connection
  3. Verify Supabase project is running (check dashboard)
  4. Check if your IP is whitelisted

Database migrations failed​

Error: Migration files not applied or schema mismatch

Solutions:

# Check migration status
supabase migration list

# Manually apply schema
psql -h db.host -U postgres -d dbname -f supabase/schema.sql

# Check migrations folder
ls supabase/migrations/

Row-level security (RLS) blocking queries​

Error: new row violates row-level security policy

Solutions:

  1. Verify user is authenticated
  2. Check RLS policies in Supabase dashboard
  3. Ensure user has required role/permissions
  4. Check policy conditions (e.g., auth.uid())

Authentication Issues​

User cannot login​

Error: Invalid login credentials or blank login page

Solutions:

  1. Verify user account exists in Supabase
  2. Check email hasn't been deleted
  3. Verify password is correct
  4. Clear browser cache/cookies

Session expired unexpectedly​

Error: Redirected to login after few minutes

Solutions:

  1. Check token expiration: usually 1 hour
  2. Implement token refresh (should be automatic)
  3. Verify VITE_SUPABASE_URL and keys are correct
  4. Check browser cookies are enabled

Cannot access admin panel​

Error: Redirected to home page or "Access denied"

Solutions:

  1. Verify user account has admin role in Supabase
  2. Check users table for role field
  3. Verify admin routes are protected correctly
  4. Clear cache and try again

Content & Media Issues​

Images not uploading​

Error: Upload fails or image doesn't appear

Solutions:

  1. Verify VITE_CLOUDINARY_CLOUD_NAME and VITE_CLOUDINARY_UPLOAD_PRESET are set
  2. Check file size (max 10MB)
  3. Verify file is valid image format
  4. Check Cloudinary dashboard for errors

Video metadata not loading​

Error: YouTube videos show no thumbnail or title

Solutions:

  1. Verify VITE_YOUTUBE_API_KEY is set and active
  2. Check YouTube API is enabled in GCP console
  3. Verify video ID is correct
  4. Check API quota hasn't been exceeded

Content won't publish​

Error: Save button doesn't work or error message appears

Solutions:

  1. Check browser console for errors (F12)
  2. Verify all required fields are filled
  3. Check network tab for failed requests
  4. Verify Supabase connection is active

Email Issues​

Welcome email not sending​

Error: User created but no email received

Solutions:

  1. Verify SMTP credentials in .env
  2. Check email not in spam folder
  3. Verify email address is valid
  4. Check backend logs: python main.py

Newsletter signup fails​

Error: Subscribe button doesn't work or shows error

Solutions:

  1. Verify email is valid format
  2. Check if email already subscribed
  3. Verify newsletter table exists in database
  4. Check backend API is running (python main.py)

Performance Issues​

Site loads slowly​

Causes: Large bundle, unoptimized images, slow database

Solutions:

  1. Build and check bundle size: npm run build
  2. Optimize images: use Cloudinary transformations
  3. Enable database caching
  4. Check network tab in dev tools
  5. Use Lighthouse (Chrome DevTools) to profile

High memory usage in dev server​

Solutions:

# Restart dev server
Ctrl+C
npm run dev

# Clear node_modules if persistent
rm -rf node_modules
npm install

Deployment Issues​

Build fails on Vercel/Netlify​

Error: Build logs show errors

Solutions:

  1. Verify all environment variables are set
  2. Check node version matches local (usually 18+)
  3. Verify build command: npm run build
  4. Check for hardcoded localhost URLs

Live site shows different content than local​

Cause: Stale cache or CDN not updated

Solutions:

  1. Clear Vercel cache and redeploy
  2. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
  3. Check environment variables match production
  4. Wait for CDN cache to invalidate (usually 5 min)

API calls returning 404​

Error: Requests to /api/* endpoints fail

Solutions:

  1. Verify VITE_API_BASE_URL points to correct server
  2. Check backend is running/deployed
  3. Verify endpoint exists in backend
  4. Check CORS headers if cross-origin
  5. Look at network tab to see actual URL being called

Git & Version Control​

Changes not appearing after commit​

Cause: File not actually staged or branch not updated

Solutions:

# Check status
git status

# Stage all changes
git add -A

# Check staged files
git diff --cached

# Commit
git commit -m "message"

Merge conflicts​

Solutions:

  1. Check affected files
  2. Resolve conflicts (search for <<<<<<<)
  3. Stage resolved files
  4. Commit merge

Getting Help​

Still stuck? Try these resources:

  1. Search docs: See Documentation Index
  2. Check logs:
    • Frontend: Browser console (F12)
    • Backend: Terminal running python main.py
    • Supabase: Dashboard → Logs
  3. Contact support: info@agentification.academy
  4. Check status pages:

Last Updated: 2025-12-24

For detailed setup information, see Development Setup.