Troubleshooting

This guide covers common issues, error messages, and solutions when using all2md. Most problems fall into a few categories: missing dependencies, file access issues, or format-specific problems.

Quick Diagnostic Steps 

When encountering issues, try these steps first:

Check Python Version

python --version
# Should be 3.10 or higher

Verify Installation

import all2md
print(all2md.__version__)

Test with Simple File
```
echo "# Test" | all2md -
```
Enable Debug Logging
```
all2md document.pdf --log-level DEBUG
```
Check File Access
```
ls -la document.pdf
file document.pdf
```

Installation Issues 

Missing Dependencies 

Error Messages:

ImportError: No module named 'fitz'
ModuleNotFoundError: No module named 'docx'
ImportError: PyMuPDF is required for PDF processing

Problem:

Format-specific dependencies are not installed.

Solutions:

# For PDF support
pip install all2md[pdf]

# For Word documents
pip install all2md[docx]

# For PowerPoint
pip install all2md[pptx]

# For all formats
pip install all2md[all]

# Check what's installed
pip list | grep -E "(all2md|pymupdf|docx|pptx|beautifulsoup4)"

Python Version Issues 

Error Messages:

ERROR: Package 'all2md' requires a different Python
SyntaxError: invalid syntax (on import)

Problem:

all2md requires Python 3.10 or higher.

Solutions:

# Check current version
python --version

# Install Python 3.10+ (recommend 3.12+)
# Via uv (recommended)
uv python install 3.12

# Via pyenv
pyenv install 3.12
pyenv global 3.12

# Via conda
conda install python=3.12

# Via system package manager
# Ubuntu/Debian: sudo apt install python3.12
# macOS: brew install python@3.12

Virtual Environment Issues 

Error Messages:

Permission denied errors
ERROR: Could not install packages due to an EnvironmentError

Problem:

Conflicting system packages or permission issues.

Solutions:

# Create fresh virtual environment
python -m venv all2md_env

# Activate it
# Windows:
all2md_env\Scripts\activate
# macOS/Linux:
source all2md_env/bin/activate

# Install all2md
pip install all2md[all]

# Verify installation
which all2md
all2md --version

File Access Problems 

File Not Found 

Error Messages:

FileNotFoundError: [Errno 2] No such file or directory
File not found: document.pdf

Solutions:

# Check file exists and permissions
ls -la document.pdf

# Use absolute path
all2md /full/path/to/document.pdf

# Check current directory
pwd
ls *.pdf

Permission Denied 

Error Messages:

PermissionError: [Errno 13] Permission denied
Permission denied: './output'

Solutions:

# Check file permissions
ls -la document.pdf

# Make file readable
chmod +r document.pdf

# Check output directory permissions
ls -la ./output
mkdir -p ./output
chmod +w ./output

Corrupted or Invalid Files 

Error Messages:

MalformedFileError: Invalid PDF file
ParsingError: Failed to parse document
Error: Could not decode file as UTF-8

Solutions:

# Verify file integrity
file document.pdf
head -c 20 document.pdf

# Try forcing format detection
all2md document.pdf --format pdf --log-level DEBUG

# For text encoding issues
all2md document.txt --format txt --log-level DEBUG

Security Presets: The new --strict-html-sanitize, --safe-mode, and --paranoid-mode flags provide pre-configured security settings for common scenarios. These are especially useful when processing untrusted HTML content. See Command Line Interface for details.

Relative Links Broken

Problem: Images or links not resolving correctly.

Solutions:

from all2md.options import HtmlOptions

options = HtmlOptions(
    attachment_mode='save',
    attachment_base_url='https://example.com'
)

all2md webpage.html --attachment-mode save --attachment-base-url "https://example.com"

Email Processing Issues 

Encoding Problems

Problem: Special characters or non-English text garbled.

Solutions:

from all2md.options import EmlOptions

# Enable HTML conversion for better encoding handling
options = EmlOptions(
    convert_html_to_markdown=True,
    clean_quotes=True
)

Thread Structure Issues

Problem: Reply chains not handled correctly.

Solutions:

from all2md.options import EmlOptions

# Adjust thread processing
options = EmlOptions(
    preserve_thread_structure=True,
    detect_reply_separators=True,
    clean_quotes=True
)

# Or disable for simple conversion
options = EmlOptions(
    preserve_thread_structure=False,
    include_headers=False
)

# CLI equivalents
all2md message.eml --eml-no-preserve-thread-structure --eml-no-include-headers

Performance Issues 

Slow Processing 

Problem: Large documents taking too long to process.

Solutions:

from all2md.options import PdfOptions

# Process specific pages only
options = PdfOptions(pages=[1, 2, 3])  # First 3 pages

# Skip images for faster processing
options = PdfOptions(attachment_mode='skip')

# Disable complex features
options = PdfOptions(
    detect_columns=False,
    enable_table_fallback_detection=False
)

# CLI equivalents
all2md document.pdf --pdf-pages "1,2,3"
all2md document.pdf --attachment-mode skip
all2md document.pdf --pdf-no-detect-columns --pdf-no-enable-table-fallback-detection

Memory Issues 

Problem: Out of memory errors with large files.

Solutions:

from all2md import to_markdown, PdfOptions

# Process in smaller chunks
total_pages = 100  # Example total
for i in range(0, total_pages, 10):
    page_chunk = list(range(i, min(i + 10, total_pages)))
    options = PdfOptions(pages=page_chunk)
    chunk_markdown = to_markdown('large.pdf', parser_options=options)
    # Process chunk_markdown

# Skip attachment processing
options = PdfOptions(attachment_mode='skip')

# CLI: Process specific page ranges
all2md large.pdf --pdf-pages "1,2,3,4,5,6,7,8,9,10" --out chunk1.md
all2md large.pdf --pdf-pages "11,12,13,14,15,16,17,18,19,20" --out chunk2.md

Command Line Issues 

Command Not Found 

Error Messages:

all2md: command not found
'all2md' is not recognized as an internal or external command

Solutions:

# Check if installed
pip list | grep all2md

# Reinstall if necessary
pip install all2md

# Use module form
python -m all2md document.pdf

# Check PATH
echo $PATH
which all2md

Argument Parsing Issues 

Error Messages:

unrecognized arguments
error: argument --format: invalid choice

Solutions:

# Check available options
all2md --help

# Verify format names
all2md document.pdf --format pdf  # not PDF

# Quote arguments with spaces
all2md document.pdf --attachment-output-dir "My Folder"

Stdin/Pipe Issues 

Problem: Reading from stdin or pipes not working.

Solutions:

# Explicit stdin
cat document.pdf | all2md -

# With format specification
cat unknown_file | all2md - --format pdf

# Check pipe status
echo "# Test" | all2md - --log-level DEBUG

Advanced Debugging 

Enable Detailed Logging 

import logging
from all2md import to_markdown

# Configure logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('all2md')

# Convert with detailed logging
markdown = to_markdown('document.pdf')

# Command line debugging
all2md document.pdf --log-level DEBUG > output.md 2> debug.log

Check File Format Detection 

from all2md import to_markdown

# Force different formats to test detection
for fmt in ['auto', 'pdf', 'txt']:
    try:
        result = to_markdown('mysterious_file', source_format=fmt)
        print(f"Format {fmt}: Success ({len(result)} chars)")
    except Exception as e:
        print(f"Format {fmt}: Failed - {e}")

Test with Minimal Example 

# Create minimal test case
with open('test.html', 'w') as f:
    f.write('<html><body><h1>Test</h1><p>Content</p></body></html>')

from all2md import to_markdown
result = to_markdown('test.html')
print(result)

Examine File Structure 

# For PDF files
pdfinfo document.pdf
pdftk document.pdf dump_data

# For Office files (they're ZIP archives)
unzip -l document.docx
unzip -l document.pptx

# For general files
file document.pdf
hexdump -C document.pdf | head -20

Getting Help 

When to Report Issues 

Report bugs when you encounter:

Crashes or exceptions with valid input files
Incorrect output that’s clearly wrong
Missing features documented but not working
Performance issues with reasonable file sizes

Before Reporting 

Update to latest version
```
pip install --upgrade all2md
```
Test with minimal example

Create the smallest possible file that reproduces the issue.
Check existing issues

Search https://github.com/thomas.villani/all2md/issues

Gather information

# System information
python --version
pip list | grep all2md
uname -a  # Linux/macOS
systeminfo  # Windows

# Debug output
all2md problematic_file.pdf --log-level DEBUG > debug.log 2>&1

How to Report 

Include in your issue report:

all2md version and Python version
Operating system and version
Minimal example that reproduces the problem
Expected vs. actual behavior
Complete error message or debug log
Steps to reproduce the issue

Good Issue Report:

Title: PDF table detection fails for merged cells

Environment:
- all2md version: 0.1.0
- Python version: 3.12.0
- OS: Ubuntu 22.04

Problem:
Tables with merged cells are not detected correctly in PDF files.

Steps to reproduce:
1. Convert attached PDF file
2. all2md test_table.pdf --log-level DEBUG
3. Table structure is lost

Expected: Table preserved with merged cells
Actual: Text runs together

Debug log attached.

Community Resources 

GitHub Issues: https://github.com/thomas.villani/all2md/issues
Documentation: https://all2md.readthedocs.io/
Stack Overflow: Tag questions with all2md

For installation or environment issues, also check the Installation Guide guide.

Troubleshooting

Quick Diagnostic Steps 

Installation Issues 

Missing Dependencies 

Python Version Issues 

Virtual Environment Issues 

File Access Problems 

File Not Found 

Permission Denied 

Corrupted or Invalid Files 

Format-Specific Issues 

PDF Problems 

Word Document Issues 

HTML Issues 

Email Processing Issues 

Performance Issues 

Slow Processing 

Memory Issues 

Command Line Issues 

Command Not Found 

Argument Parsing Issues 

Stdin/Pipe Issues 

Advanced Debugging 

Enable Detailed Logging 

Check File Format Detection 

Test with Minimal Example 

Examine File Structure 

Getting Help 

When to Report Issues 

Before Reporting 

How to Report 

Community Resources 