Troubleshooting Guide

This guide covers common issues you might encounter during the workshop and their solutions.

Installation Issues

Python Version Errors

Problem: Assertion error about Python version

AssertionError: Use Python 3.11, 3.12, or 3.13 to run this notebook.

Solution:

1. Check your Python version:

   python3 --version
   

2. If using an older version, install a supported version:

   • macOS: brew install python@3.12
   • Ubuntu: sudo apt install python3.12
   • Windows: Download from python.org

3. Create a new virtual environment with the correct version:

   python3.12 -m venv venv
   source venv/bin/activate
   

Dependency Installation Failures

Problem: pip install fails with compilation errors

Solution:

1. Ensure you have build tools installed:

   • macOS: xcode-select --install
   • Ubuntu: sudo apt install build-essential
   • Windows: Install Visual Studio Build Tools

2. Try using uv for faster, more reliable installs:

   pip install uv
   uv pip install docling
   

Memory Errors During Installation

Problem: Installation runs out of memory

Solution:

1. Close other applications to free memory
2. Install packages one at a time instead of all at once

3. Use --no-cache-dir flag:

   pip install --no-cache-dir docling
   

Model Loading Issues

VLM Models Won't Load

Problem: Error loading Granite-Docling or Granite Vision models

Solution:

1. Check available memory - VLM models require 4-8 GB RAM
2. Try a smaller model first

3. On Apple Silicon, the granite_docling preset uses the MLX build automatically. Make sure MLX is installed with docling[vlm]:

   from docling.datamodel.pipeline_options import VlmConvertOptions, VlmPipelineOptions
   
   vlm_pipeline_options = VlmPipelineOptions(
       vlm_options=VlmConvertOptions.from_preset("granite_docling"),
   )
   

Ollama/LM Studio Connection Errors

Problem: Cannot connect to local model server

Solution:

1. Verify the server is running:

   curl http://localhost:11434/api/tags  # Ollama
   curl http://localhost:1234/v1/models  # LM Studio
   

2. Check the port is correct in your code

3. Ensure no firewall is blocking localhost connections

Document Processing Issues

PDF Conversion Fails

Problem: Error converting certain PDFs

Solution:

1. Try enabling OCR for scanned documents:

   PdfPipelineOptions(do_ocr=True)
   

2. Check if the PDF is password-protected

3. Try converting a simpler PDF first to verify setup

Out of Memory During Conversion

Problem: Kernel dies or out of memory error

Solution:

1. Process fewer pages at a time

2. Reduce image resolution:

   PdfPipelineOptions(images_scale=1.0)  # Instead of 2.0
   

3. Disable features you don't need:

   PdfPipelineOptions(
       generate_page_images=False,
       generate_picture_images=False,
   )
   

Slow Document Processing

Problem: Conversion takes too long

Solution:

1. Disable OCR if not needed (do_ocr=False)
2. Reduce image quality for faster processing
3. Use a GPU if available

4. For large documents, save JSON output and reuse:

   doc.save_as_json("document.json")
   # Later:
   doc = DoclingDocument.load_from_json("document.json")
   

Docling Service Issues

Notebook Still Converts Locally

Problem: The notebook prints Docling conversions will run locally although you set up a Docling service

Solution:

1. Check the variable name is exactly DOCLING_SERVICE_URL
2. If you exported it in a terminal, restart Jupyter from that terminal so the kernel sees it
3. For Colab, check the Secrets tab has the value and notebook access is enabled

Authentication Errors

Problem: ServiceError with status=401

Solution: Check DOCLING_SERVICE_API_KEY holds the API key for the service at DOCLING_SERVICE_URL

Conversion Timeouts

Problem: TaskTimeoutError for large documents or picture descriptions

Solution: Give the client more time, for example DoclingServiceClient(url=..., api_key=..., job_timeout=1800)

Usage Limits

Problem: UsageLimitExceededError

Solution: Your service plan or trial has reached its page limit. Check your plan, or unset DOCLING_SERVICE_URL to run Docling locally.

Replicate API Issues

Rate Limiting

Problem: "Too many requests" error from Replicate

Solution:

1. Add delays between requests
2. Use local inference instead (LM Studio or Ollama)
3. Contact Replicate for higher rate limits

API Token Issues

Problem: Authentication errors

Solution:

1. Verify your token is set:

   echo $REPLICATE_API_TOKEN
   

2. Regenerate your token at replicate.com/account/api-tokens

3. For Colab, check the Secrets tab has the correct value

Vector Database Issues

Duplicate or Stale Results from ChromaDB

Problem: Retrieval returns chunks from an earlier run, or the same chunk twice

Solution:

1. The RAG notebooks keep ChromaDB in memory, so restart the kernel and run the cells in order
2. After switching the embeddings model, rebuild the vector database: embeddings from different models can't be mixed

Jupyter Notebook Issues

Kernel Dies Unexpectedly

Problem: Jupyter kernel crashes during execution

Solution:

1. Check system memory usage
2. Run memory-intensive cells one at a time
3. Restart the kernel and run cells in order
4. Consider using Google Colab for more resources

Widgets Not Displaying

Problem: ipywidgets not showing in notebook

Solution:

1. Install ipywidgets in the same environment as Jupyter:

   pip install ipywidgets
   

2. Restart Jupyter after installation

Getting Help

If you encounter an issue not covered here:

1. Check the Docling GitHub Issues
2. Search the Docling Discussions
3. Open a new issue with:
   • Your Python version
   • Your operating system
   • The complete error message
   • Steps to reproduce the issue