Common issues

​

LLM API key errors

1. Wrong key: Verify the key by running a test request directly against your provider’s API outside of DeepTutor.
2. Incorrect LLM_HOST: Every provider has a different base URL. Make sure LLM_HOST matches the provider set in LLM_BINDING.

   Provider	LLM_HOST
   OpenAI	https://api.openai.com/v1
   Azure OpenAI	https://<resource>.openai.azure.com/openai/deployments/<deployment>
   DeepSeek	https://api.deepseek.com/v1
   Anthropic	https://api.anthropic.com/v1
   Ollama (local)	http://localhost:11434/v1

3. LLM_BINDING mismatch: The LLM_BINDING value must match the provider you are using (e.g., openai, anthropic, deepseek, ollama). An incorrect binding causes the client to send requests in the wrong format.
4. Key in wrong variable: Confirm the key is in LLM_API_KEY, not EMBEDDING_API_KEY or another variable.

# Print the LLM config lines from your .env (does not print the key itself)
grep -E "^LLM_" .env

​

Embedding model errors

• EMBEDDING_HOST points to the wrong endpoint for your provider.
• EMBEDDING_DIMENSION does not match the actual output dimension of your model. For example, text-embedding-3-small outputs 1536 dimensions by default, while text-embedding-3-large outputs 3072.
• You are using an OpenAI-compatible local model (e.g., via Ollama or LM Studio) but EMBEDDING_BINDING is set to openai instead of ollama or lm_studio.

EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_HOST=https://api.openai.com/v1
EMBEDDING_DIMENSION=1536   # must match the model's actual output size

​

Knowledge base creation failures

​

Document parsing errors

• Corrupted or password-protected PDF: DeepTutor cannot parse encrypted PDFs. Remove the password with a PDF tool before uploading.
• Scanned PDF without OCR text layer: The default parser relies on extractable text. Use a PDF that has been OCR-processed, or enable the Docling parser (available in v0.5.2+) which handles scanned documents.
• MinerU model not downloaded: Question generation’s mimic mode and some parsing pipelines use MinerU, which downloads models from HuggingFace on first use. If you are behind a firewall or running in an offline environment, set HF_ENDPOINT to a mirror or HF_HUB_OFFLINE=1 with a pre-downloaded cache.
  # Use a HuggingFace mirror
  HF_ENDPOINT=https://your-hf-mirror.example.com
  
  # Or force offline mode (models must already be in HF_HOME)
  HF_HUB_OFFLINE=1
  HF_HOME=/app/data/hf
  

​

File size and count limits

• Split large PDFs into smaller sections before uploading.
• Upload documents in smaller batches rather than all at once.
• Monitor memory usage in the terminal while processing runs.

​

uvloop.Loop error during numbered items extraction

ValueError: Can't patch loop of type <class 'uvloop.Loop'>

# Recommended: use the shell script
./scripts/extract_numbered_items.sh <kb_name>

# Alternative: call the Python module directly
python src/knowledge/extract_numbered_items.py \
  --kb <kb_name> \
  --base-dir ./data/knowledge_bases

​

Docker volume permissions

# Make the data directory writable by the container process
chmod -R 777 data/

# Or change ownership to match the container's user (UID 1000 is common)
sudo chown -R 1000:1000 data/

services:
  deeptutor:
    user: "1000:1000"

​

Memory and resource issues during document processing

• Building a knowledge base is the most memory-intensive operation. Ensure the host has at least 4 GB of free RAM for typical workloads.
• Reduce the number of documents processed at the same time.
• If running in Docker, increase the container’s memory limit:
  docker run --memory="4g" ...
  
• For very large corpora, run the knowledge base builder via the CLI to avoid the overhead of the web server:
  python -m src.knowledge.start_kb init <kb_name> --docs <pdf_path>
  

​

Search provider not working

1. SEARCH_API_KEY is not set: Web search is disabled unless you provide a key for your chosen provider.
   SEARCH_PROVIDER=perplexity
   SEARCH_API_KEY=pplx-xxx
   
2. Wrong provider selected: The supported values for SEARCH_PROVIDER are perplexity, tavily, serper, jina, and exa. An unrecognized value disables web search.
3. Global web search switch is off: The tools.web_search.enabled flag in config/main.yaml is a global override. If it is set to false, web search is disabled regardless of your API key.
   # config/main.yaml
   tools:
     web_search:
       enabled: true
   
4. Firewall blocking outbound requests: Verify that the backend can reach the search provider’s API from the host machine.

​

Chinese language support

1. Set the system language in config/main.yaml:
   system:
     language: zh
   
2. Ensure your LLM supports Chinese output. Most general-purpose models (GPT-4o, DeepSeek, Claude) do. Smaller or quantized local models may produce lower-quality Chinese text.
3. Restart the backend after changing the language setting.

​

Node.js version compatibility

node --version   # must be v18.x.x or higher
npm --version

conda install -c conda-forge "nodejs>=18"

nvm install 18
nvm use 18
# Persist across sessions
nvm alias default 18

npm install --prefix web

​

Still stuck?

• Browse or open an issue on GitHub.
• Ask the community on Discord.
• Check data/user/logs/ for detailed backend logs that may contain the root cause.