Troubleshooting

​

Installation Issues

​

Docker-related Issues

If you’re having issues with Docker setup:

1. Ensure Docker Desktop is properly installed and running
2. Try rebuilding the image:

   docker-compose down
   docker-compose build --no-cache
   docker-compose up
   

​

Python Environment Issues

If you’re having issues with the Python environment:

1. Make sure you have Python 3.11+ installed:

   python --version
   

2. If using uv package manager:

   uv --version
   # If not installed
   pip install uv
   

3. Recreate the virtual environment:

   cd backend
   rm -rf .venv # or venv
   uv venv .venv # or python -m venv venv
   source .venv/bin/activate # or venv\Scripts\activate on Windows
   uv pip install -r requirements.txt # or pip install -r requirements.txt
   

​

Frontend Dependency Issues

If you encounter frontend dependency issues:

1. Make sure you’re using Node.js 20+:

   node --version
   

2. Clean and reinstall dependencies:

   cd frontend
   rm -rf node_modules
   rm package-lock.json
   npm install
   

​

Runtime Errors

​

API Connection Issues

If you can’t connect to the API:

1. Check if the API server is running:

   curl http://localhost:8001/api/health
   

2. Verify ports aren’t being used by other applications

   # On Mac/Linux
   lsof -i :8001
   
   # On Windows
   netstat -ano | findstr :8001
   

3. Ensure CORS is properly configured if accessing from a different origin

​

Polars Data Processing Issues

If you’re experiencing issues with Polars data processing:

1. Check the Polars version is compatible:

   import polars as pl
   print(pl.__version__)
   

2. Ensure your data files are in the supported formats (Parquet, CSV, Arrow)

3. Verify your data schema is consistent

​

Common Error Codes

​

Getting Additional Help

If you can’t find a solution to your problem here, please:

1. Check our FAQs page
2. Open an issue on GitHub with detailed information:
   • Steps to reproduce
   • Expected behavior
   • Actual behavior
   • Your environment (OS, browser, Docker/Node/Python versions)
   • Relevant logs

​

Backend Logs

To view detailed backend logs:

# When running with docker-compose
docker-compose logs backend

# When running directly
cd backend
ENVIRONMENT=development uvicorn main:app --reload --host 0.0.0.0 --port 8001 --log-level debug

​

Frontend Logs

To view frontend development logs:

cd frontend
npm run dev -- --debug

Browser console logs can also provide useful information about frontend issues.

​

Getting Additional Help

If you can’t find a solution to your problem here, please:

1. Check our FAQs page
2. Join our Discord community
3. Open an issue on GitHub