Description
After a clean install in Windows the app stops with the error "ImportError: cannot import name 'HfFolder' from 'huggingface_hub' (C:\Kotaemon\install_dir\env\lib\site-packages\huggingface_hub_init_.py) ". With the Geminoi's Pro help after many iterations I managed to get an installation that works. The following is the report from Gemini that consolidates all the issues we faced and how to fix them. Hope that this will help improve the app.
During a fresh local Windows installation of Kotaemon (v0.11.3), the setup script successfully creates the Conda environment but consistently fails to launch the UI due to several unpinned dependency conflicts and missing utility packages.
Below is a breakdown of the specific errors encountered and the root causes, which can likely be resolved by updating the package manager requirements (e.g., pyproject.toml or requirements.txt).
Issue 1: Gradio / HuggingFace Hub Conflict
Error: ImportError: cannot import name 'HfFolder' from 'huggingface_hub'
Root Cause: The installer pulls the absolute latest version of huggingface-hub. Recent versions of the hub have deprecated and removed HfFolder. However, the version of gradio installed by the script still relies on HfFolder, causing a fatal crash during UI initialization.
Fix Applied: Downgraded and pinned huggingface-hub==0.23.2.
Issue 2: The LangChain "0.1 vs 0.3" Version Matrix Collision
Errors: ModuleNotFoundError: No module named 'langchain.schema', followed by cannot import name 'LangSmithParams', followed by ModuleNotFoundError: No module named 'langchain_core.memory'.
Root Cause: This was the most complex issue. The ktem base codebase expects legacy LangChain schemas (circa langchain 0.1.x). However, because dependencies are unpinned, the installer fetches langchain 0.3.x (or 1.3.x for core), where langchain.schema has been removed.
If you blindly downgrade langchain-core to 0.1.x, it breaks the dynamically loaded LLM plugins (langchain-ollama, langchain-anthropic, etc.), which expect newer langchain-core structures like LangSmithParams.
The underlying issue is that the core app and the dynamically loaded LLM provider plugins are downloading incompatible versions of the LangChain ecosystem.
Fix Applied: We forced the entire LangChain ecosystem into the 0.2.x release line. This acted as a bridge, retaining enough legacy schema support for ktem while satisfying the minimum requirements for the modern LLM plugins.
Issue 3: Missing Utility Libraries
Errors: ModuleNotFoundError: No module named 'cachetools' and ModuleNotFoundError: No module named 'voyageai'.
Root Cause: When attempting to initialize the UI and the embedding models, the application calls for cachetools (in utils/hf_papers.py) and voyageai (in embeddings/voyageai.py). Neither of these are installed by default during the Windows .bat setup, causing the startup to halt.
Fix Applied: Manually ran pip install cachetools voyageai.
Note on VoyageAI: Running pip install voyageai triggered a pip auto-upgrade that pushed langchain-core to 1.3.2, destroying the Langchain fix from Issue 2. We had to reinstall voyageai alongside strict langchain pins.
Issue 4: Strict Pydantic Ceilings
Error Warning: kotaemon 0.11.3 requires pydantic<=2.10.6, but you have pydantic 2.13.3 which is incompatible. (and vice versa for mcp and sqlmodel which ask for >=2.11.0).
Root Cause: Conflicting version requirements between internal modules.
Fix Applied: Pinned pydantic==2.10.6. The app seems stable at this version despite the strictness warnings from pip.
Issue 5: Silent Port Binding on Crash (Windows Specific)
Error: [Errno 10048] error while attempting to bind on address ('127.0.0.1', 31415)
Root Cause: When the Gradio UI crashes due to a module error, the llama-cpp-python background inference server continues running silently in the Windows command prompt session. On subsequent attempts to run run_windows.bat, the script tries to spin up the local server again, crashes because the port is in use, and dies.
Recommendation: Consider adding a port-kill or cleanup routine at the beginning of run_windows.bat to terminate orphaned llama-cpp tasks on port 31415 before attempting to boot the server.
Reproduction steps
1. Download kotaemon-app.zip
2. Extract contents in c:\kotaemon
3. Run C:\Kotaemon\scripts\run_windows.bat
4. After the installation is finished the error is "ImportError: cannot import name 'HfFolder' from 'huggingface_hub' (C:\Kotaemon\install_dir\env\lib\site-packages\huggingface_hub\__init__.py) "
Screenshots
Logs
Browsers
No response
OS
No response
Additional information
No response
Description
After a clean install in Windows the app stops with the error "ImportError: cannot import name 'HfFolder' from 'huggingface_hub' (C:\Kotaemon\install_dir\env\lib\site-packages\huggingface_hub_init_.py) ". With the Geminoi's Pro help after many iterations I managed to get an installation that works. The following is the report from Gemini that consolidates all the issues we faced and how to fix them. Hope that this will help improve the app.
During a fresh local Windows installation of Kotaemon (v0.11.3), the setup script successfully creates the Conda environment but consistently fails to launch the UI due to several unpinned dependency conflicts and missing utility packages.
Below is a breakdown of the specific errors encountered and the root causes, which can likely be resolved by updating the package manager requirements (e.g., pyproject.toml or requirements.txt).
Issue 1: Gradio / HuggingFace Hub Conflict
Issue 2: The LangChain "0.1 vs 0.3" Version Matrix Collision
Issue 3: Missing Utility Libraries
Errors: ModuleNotFoundError: No module named 'cachetools' and ModuleNotFoundError: No module named 'voyageai'.
Root Cause: When attempting to initialize the UI and the embedding models, the application calls for cachetools (in utils/hf_papers.py) and voyageai (in embeddings/voyageai.py). Neither of these are installed by default during the Windows .bat setup, causing the startup to halt.
Fix Applied: Manually ran pip install cachetools voyageai.
Note on VoyageAI: Running pip install voyageai triggered a pip auto-upgrade that pushed langchain-core to 1.3.2, destroying the Langchain fix from Issue 2. We had to reinstall voyageai alongside strict langchain pins.
Issue 4: Strict Pydantic Ceilings
Error Warning: kotaemon 0.11.3 requires pydantic<=2.10.6, but you have pydantic 2.13.3 which is incompatible. (and vice versa for mcp and sqlmodel which ask for >=2.11.0).
Root Cause: Conflicting version requirements between internal modules.
Fix Applied: Pinned pydantic==2.10.6. The app seems stable at this version despite the strictness warnings from pip.
Issue 5: Silent Port Binding on Crash (Windows Specific)
Error: [Errno 10048] error while attempting to bind on address ('127.0.0.1', 31415)
Root Cause: When the Gradio UI crashes due to a module error, the llama-cpp-python background inference server continues running silently in the Windows command prompt session. On subsequent attempts to run run_windows.bat, the script tries to spin up the local server again, crashes because the port is in use, and dies.
Recommendation: Consider adding a port-kill or cleanup routine at the beginning of run_windows.bat to terminate orphaned llama-cpp tasks on port 31415 before attempting to boot the server.
Reproduction steps
Screenshots
Logs
Browsers
No response
OS
No response
Additional information
No response