Skip to main content

Troubleshooting Guide

This guide covers common issues and solutions you might encounter while working with the MLContext platform.

🚀 Setup Issues​

Node.js and Dependencies​

Issue: pnpm install fails or takes too long

Solutions:

  • Ensure Node.js 18+ is installed
  • Clear npm/pnpm cache: pnpm store prune
  • Delete node_modules and pnpm-lock.yaml, then reinstall
  • Check network connectivity and proxy settings

Issue: TypeScript compilation errors

Solutions:

  • Run pnpm type-check to see detailed errors
  • Ensure all dependencies are installed
  • Check TypeScript configuration in tsconfig.json
  • Restart TypeScript language server in your editor

Python and ML Service​

Issue: Python dependencies installation fails

Solutions:

  • Ensure Python 3.9+ is installed
  • Use virtual environment: python -m venv venv
  • Activate virtual environment before installing dependencies
  • Check pip version and upgrade if needed

Issue: FastAPI server won't start

Solutions:

  • Check if port 8000 is already in use
  • Verify all environment variables are set
  • Check Python path and module imports
  • Review error logs for specific issues

Database and Supabase​

Issue: Cannot connect to Supabase

Solutions:

  • Verify Supabase URL and API keys in environment
  • Check Supabase project status
  • Ensure database is accessible
  • Verify network connectivity

Issue: Database migrations fail

Solutions:

  • Check database connection
  • Verify migration file syntax
  • Ensure proper permissions
  • Run migrations in correct order

🎬 DAGGH Frontend Issues​

Development Server​

Issue: Next.js development server won't start

Solutions:

  • Check if port 3000 is in use
  • Clear Next.js cache: rm -rf .next
  • Restart development server
  • Check for syntax errors in configuration files

Issue: Hot reload not working

Solutions:

  • Restart development server
  • Clear browser cache
  • Check file watcher limits on Linux/Mac
  • Verify file permissions

UI and Styling​

Issue: Tailwind styles not applying

Solutions:

  • Check Tailwind configuration
  • Verify class names are correct
  • Clear build cache
  • Check for CSS purging issues

Issue: Framer Motion animations not working

Solutions:

  • Check React version compatibility
  • Verify animation props
  • Check for console errors
  • Test with simplified animations

🤖 ML Service Issues​

Algorithm Performance​

Issue: Recommendations taking too long

Solutions:

  • Check database query performance
  • Review algorithm complexity
  • Add caching for frequently accessed data
  • Profile code to identify bottlenecks

Issue: Poor recommendation quality

Solutions:

  • Verify training data quality
  • Check feature engineering
  • Review algorithm parameters
  • Test with different model configurations

API Issues​

Issue: FastAPI endpoints returning errors

Solutions:

  • Check request format and validation
  • Review endpoint documentation
  • Verify authentication
  • Check server logs for detailed errors

📚 Documentation Issues​

Docusaurus Problems​

Issue: Documentation site won't build

Solutions:

  • Check for broken links
  • Verify markdown syntax
  • Clear Docusaurus cache
  • Check for missing dependencies

Issue: Navigation not updating

Solutions:

  • Check sidebars.ts configuration
  • Verify file paths
  • Restart development server
  • Clear browser cache

🔗 Integration Issues​

API Communication​

Issue: Frontend can't connect to ML service

Solutions:

  • Verify service URLs and ports
  • Check CORS configuration
  • Verify API keys and authentication
  • Test endpoints with curl or Postman

Issue: Real-time features not working

Solutions:

  • Check Supabase Realtime configuration
  • Verify WebSocket connections
  • Check for network firewalls
  • Review real-time subscription code

🐛 Common Error Messages​

"Module not found"​

  • Check import paths
  • Verify module installation
  • Check file naming and extensions
  • Review TypeScript path mapping

"Permission denied"​

  • Check file permissions
  • Verify user privileges
  • Review security settings
  • Check environment access

"Port already in use"​

  • Find and kill process using port
  • Use different port
  • Check for multiple instances
  • Review port configuration

"Authentication failed"​

  • Verify API keys
  • Check token expiration
  • Review authentication flow
  • Check user permissions

🔧 Development Tools​

VS Code Issues​

Issue: TypeScript errors not showing

Solutions:

  • Restart TypeScript language server
  • Check VS Code extensions
  • Verify workspace settings
  • Update TypeScript version

Issue: Debugging not working

Solutions:

  • Check debug configuration
  • Verify source maps
  • Check breakpoint placement
  • Review debug console output

Git Issues​

Issue: Merge conflicts

Solutions:

  • Use git merge tools
  • Communicate with team
  • Review conflicting changes
  • Test after resolution

📞 Getting Help​

When to Ask for Help​

  • After trying documented solutions
  • When encountering new error patterns
  • For architecture decisions
  • When stuck for more than 30 minutes

How to Ask for Help​

  1. Describe the problem clearly
  2. Include error messages
  3. Share relevant code snippets
  4. Mention what you've already tried
  5. Provide environment details

Where to Get Help​

  • GitHub Issues for bugs
  • Team chat for quick questions
  • Documentation for reference
  • Code reviews for guidance

📝 Reporting Issues​

Bug Reports Should Include​

  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment information
  • Error messages or logs
  • Screenshots if relevant

Feature Requests Should Include​

  • Clear description of the need
  • Use case examples
  • Proposed solution
  • Impact assessment
  • Alternative considerations

Still having issues? Don't hesitate to reach out to the team or create an issue in the repository!