docling-project / docling-project/docling

Memory leak in DoclingParseV2DocumentBackend - 13GB accumulation on repeated conversions

Open
#2,209 15 comments 1 reaction 0 assignees View on GitHub
question
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
2d 21h
Merged PRs (30d)
84

Description

## ๐Ÿ› **Bug Report: Severe Memory Leak in DoclingParseV2DocumentBackend**

### **๐Ÿ“Š Summary**
DoclingParseV2DocumentBackend accumulates memory on repeated conversions and never releases it, causing catastrophic memory leaks that can consume 10GB+ RAM in minutes.

### **๐Ÿ” Environment**
- **Backend**: DoclingParseV2DocumentBackend
- **Document Type**: PDF (0.41 MB, 35 pages)
- **Configuration**: Table structure enabled, FAST mode
- **System**: Windows/Python

### **๐Ÿ’ฅ Issue Details**
When reusing a single `DocumentConverter` instance with `DoclingParseV2DocumentBackend` for multiple conversions, memory accumulates exponentially:

**Memory progression:**
```
Initial: 500 MB
After 1st conversion: 13,682 MB (+13.2 GB!)
2nd conversion starts: 13,682 MB (no cleanup)
```

### **๐Ÿ”ฌ Reproduction Steps**
```python
# Create converter once
converter = DocumentConverter(
format_options={
InputFormat.PDF: PdfFormatOption(
pipeline_options=pipeline_options,
backend=DoclingParseV2DocumentBackend
)
}
)

# Multiple conversions with same converter
for i in range(3):
result = converter.convert("document.pdf")
print(f"Memory: {check_memory()} MB")
del result # This doesn't help
gc.collect() # This doesn't help either
```

### **๐Ÿ“ˆ Expected Behavior**
- Memory should stabilize after first conversion
- Subsequent conversions should only add minimal overhead
- `del result` + `gc.collect()` should free conversion memory
- Memory usage should be predictable and bounded

### **๐Ÿšจ Actual Behavior**
- Memory grows by 10GB+ per conversion
- No memory is freed between conversions
- Backend holds onto all processed document data internally
- System becomes unusable after 2-3 conversions

### **๐Ÿ” Root Cause Analysis**
The issue appears to be in `DoclingParseV2DocumentBackend` internal memory management:

1. **Internal caches not cleared**: Backend accumulates processed pages/tables
2. **Document references retained**: Converted documents stay in memory indefinitely
3. **Model buffers growing**: ML model intermediate data accumulates
4. **No cleanup mechanism**: Backend has no way to clear internal state

### **๐Ÿ’ก Current Workaround**
```python
# Recreate converter every few conversions
if conversion_count % 3 == 0:
del converter
gc.collect()
converter = DocumentConverter(...) # Fresh instance
```

### **๐ŸŽฏ Requested Fix**
1. **Add cleanup method**: `backend.clear_cache()` or similar
2. **Auto-cleanup**: Automatically free memory after each conversion
3. **Memory bounds**: Limit internal cache size
4. **Documentation**: Warn about memory accumulation with reused converters

### **๐Ÿ“Š Impact**
- **Severity**: Critical - makes batch processing impossible
- **Use cases affected**:
- Batch document conversion
- Performance testing
- Long-running services
- Resource-constrained environments

### **๐Ÿ”ง Test Case**
```python
def test_memory_leak():
converter = DocumentConverter(backend=DoclingParseV2DocumentBackend)
initial_memory = get_memory()

for i in range(3):
result = converter.convert("test.pdf")
current_memory = get_memory()
print(f"Conversion {i+1}: {current_memory - initial_memory} MB increase")
del result
gc.collect()

# Expected: Memory increase should plateau
# Actual: Memory increases by GBs each iteration
```

This bug makes `DoclingParseV2DocumentBackend` unsuitable for any scenario requiring multiple conversions with the same converter instance.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.