Troubleshooting Guide¶

Platform Requirements

Linux Only - NetIntel-OCR runs only on Linux systems.

Python 3.11 or 3.12 Only - Other versions are not supported.

If you're on Windows/Mac or using a different Python version, these are likely the cause of your issues.

New in v0.1.17: Hierarchical CLI

NetIntel-OCR v0.1.17 uses a new hierarchical command structure. If commands aren't working, make sure you're using the new syntax: - OLD: netintel-ocr document.pdf - NEW: netintel-ocr process pdf document.pdf

Common Issues and Solutions¶

Platform Issues¶

Wrong Operating System¶

ERROR: Unsupported platform detected
ERROR: Module compilation failed
ERROR: Binary wheel not available

Solution:

# Check your OS (must be Linux)
uname -s
# Expected: Linux

# NetIntel-OCR requires Linux. Options:
# 1. Use WSL2 on Windows
# 2. Use a Linux VM
# 3. Use a Linux container
# 4. Deploy to a Linux server

Wrong Python Version¶

ERROR: Python 3.11 or 3.12 required
ERROR: Unsupported Python version
ERROR: Module 'netintel_ocr' has no attribute...

Solution:

# Check Python version (MUST be 3.11.x or 3.12.x)
python --version

# Install Python 3.11 on Ubuntu/Debian
sudo apt update && sudo apt install python3.11 python3.11-venv python3.11-dev

# Install Python 3.12 on Ubuntu/Debian  
sudo apt install python3.12 python3.12-venv python3.12-dev

# Create virtual environment with correct version
python3.11 -m venv venv
source venv/bin/activate

# Verify version in virtual environment
python --version  # Must show 3.11.x or 3.12.x

Missing Dependencies¶

ERROR: No module named 'pymupdf'
ERROR: ImportError: libGL.so.1: cannot open shared object file

Solution:

# Install Linux system dependencies first
sudo apt-get update
sudo apt-get install -y \
    python3.11-dev \  # or python3.12-dev
    gcc g++ \
    libgl1-mesa-glx \
    libglib2.0-0 \
    libsm6 libxext6 libxrender-dev \
    libgomp1

# Then reinstall with all dependencies
pip install --upgrade netintel-ocr[all]

# Or install missing module
pip install pymupdf pillow opencv-python-headless

C++ Extension Build Failure¶

ERROR: Failed building wheel for netintel-ocr
ERROR: Microsoft Visual C++ 14.0 is required (Windows error)

Solution:

# This is a Windows error - NetIntel-OCR only supports Linux
# Switch to a Linux environment

# On Linux, install build tools:
sudo apt-get install build-essential python3.11-dev
# or
sudo yum install gcc gcc-c++ python3.11-devel

Ollama Connection Issues¶

Ollama Not Running¶

ERROR: Connection refused to localhost:11434

Solution:

# Start Ollama
ollama serve

# Check if running
curl http://localhost:11434/api/tags

# Start in background
nohup ollama serve > ollama.log 2>&1 &

Remote Ollama Host¶

ERROR: Cannot connect to Ollama

Solution:

# Set environment variable
export OLLAMA_HOST=http://192.168.1.100:11434

# Or use CLI parameter (v0.1.17 syntax)
netintel-ocr process pdf document.pdf --ollama-host http://192.168.1.100:11434

# Test connection
curl $OLLAMA_HOST/api/tags

Model Issues¶

Model Not Found¶

ERROR: Model 'qwen2.5vl:7b' not found

Solution:

# List available models
ollama list

# Pull missing model
ollama pull qwen2.5vl:7b

# Use available model (v0.1.17 syntax)
netintel-ocr process pdf document.pdf --network-model llava:latest

Out of Memory¶

ERROR: Out of memory (OOM)

Solution:

# Use smaller model
netintel-ocr process file document.pdf --network-model minicpm-v:latest

# Limit context size
netintel-ocr process file document.pdf --max-context 2048

# Process fewer pages
netintel-ocr process file document.pdf --pages 1-10

# Free memory
ollama stop all

Processing Errors¶

PDF Read Error¶

ERROR: Cannot read PDF file

Solution:

# Check file exists and is valid
file document.pdf
pdfinfo document.pdf

# Try repairing PDF
qpdf --replace-input document.pdf

# Convert with ghostscript
gs -sDEVICE=pdfwrite -o fixed.pdf document.pdf

Timeout During Processing¶

ERROR: Processing timeout after 300 seconds

Solution:

# Increase timeout
netintel-ocr process pdf document.pdf --timeout 600

# Use faster model
netintel-ocr process pdf document.pdf --network-model bakllava:latest

# Process in smaller chunks
netintel-ocr process pdf document.pdf --start 1 --end 20
netintel-ocr process pdf document.pdf --start 21 --end 40

Mermaid Parse Error¶

ERROR: Parse error on line 3

Solution:

# Enable auto-fix
netintel-ocr process pdf document.pdf --fix-mermaid

# Use robust validator
netintel-ocr process pdf document.pdf --validate-mermaid

# Disable Mermaid generation
netintel-ocr process pdf document.pdf --no-mermaid

Vector Store Issues¶

Milvus Connection Failed¶

ERROR: Cannot connect to Milvus at localhost:19530

Solution:

# Start Milvus
docker run -d --name milvus \
  -p 19530:19530 \
  milvusdb/milvus:latest

# Check connection
python -c "from pymilvus import connections; connections.connect()"

# Use different host
netintel-ocr process pdf document.pdf --milvus-host milvus.server:19530

Collection Already Exists¶

ERROR: Collection 'network_docs' already exists

Solution:

# Drop existing collection
netintel-ocr db cleanup --collection network_docs

# Or use different collection
netintel-ocr process pdf document.pdf --collection network_docs_v2

# Append to existing
netintel-ocr process pdf document.pdf --append-collection network_docs

Performance Issues¶

Slow Processing¶

Symptoms: Processing takes >30s per page

Solutions:

# Use faster models
netintel-ocr process pdf document.pdf --fast-mode

# Enable GPU
netintel-ocr process pdf document.pdf --gpu

# Disable context extraction
netintel-ocr process pdf document.pdf --no-context

# Use cached models
netintel-ocr process pdf document.pdf --cache-models

High Memory Usage¶

Symptoms: System becomes unresponsive

Solutions:

# Limit memory usage
netintel-ocr process pdf document.pdf --max-memory 4GB

# Process sequentially
netintel-ocr process pdf document.pdf --no-parallel

# Clear cache
netintel-ocr system cleanup --cache
rm -rf ~/.cache/netintel-ocr

Output Issues¶

Missing Output Files¶

No output files generated

Solution:

# Check output directory
ls -la output/

# Specify output directory
netintel-ocr process pdf document.pdf --output ./my-output

# Check permissions
chmod 755 output/
chmod 644 document.pdf

Corrupted Mermaid Diagrams¶

Symptoms: Mermaid diagrams don't render

Solution:

# Validate Mermaid syntax
netintel-ocr system validate-mermaid output/page_005_network.md

# Re-process with fixes
netintel-ocr process pdf document.pdf --start 5 --end 5 --fix-mermaid

# Use different Mermaid version
netintel-ocr process pdf document.pdf --mermaid-version 10.0.0

v0.1.17 CLI Migration Issues¶

Command Not Found¶

ERROR: No such command "document.pdf"
ERROR: Invalid command

Cause: Using old v0.1.16 syntax with v0.1.17

Solution:

# OLD (v0.1.16 and earlier) - DEPRECATED
netintel-ocr document.pdf
netintel-ocr --query "search term"
netintel-ocr --api

# NEW (v0.1.17) - CORRECT
netintel-ocr process pdf document.pdf
netintel-ocr db query "search term"
netintel-ocr server api

# View all command groups
netintel-ocr --help

# View specific group commands
netintel-ocr process --help
netintel-ocr kg --help
netintel-ocr config --help

Knowledge Graph Issues¶

FalkorDB Connection Issues¶

ERROR: FalkorDB connection refused at localhost:6379
ERROR: Cannot connect to graph database

Solution:

# Start FalkorDB container
docker run -d --name falkordb -p 6379:6379 falkordb/falkordb:latest

# Check if FalkorDB is running
docker ps | grep falkordb
redis-cli -p 6379 ping

# Initialize KG system
netintel-ocr kg init

# Use custom FalkorDB host
export FALKORDB_HOST=192.168.1.100
export FALKORDB_PORT=6379
netintel-ocr kg init --falkordb-host $FALKORDB_HOST

PyKEEN Installation Issues¶

ERROR: PyKEEN not installed
ERROR: No module named 'pykeen'

Solution:

# Install KG dependencies
pip install pykeen torch falkordb

# Check all KG requirements
netintel-ocr kg check-requirements --verbose

# If torch fails, install CPU version
pip install torch --index-url https://download.pytorch.org/whl/cpu

KG Training Issues¶

ERROR: Failed to train embeddings
ERROR: CUDA out of memory

Solution:

# Use CPU for training
netintel-ocr kg train-embeddings --device cpu

# Reduce batch size
netintel-ocr kg train-embeddings --batch-size 64

# Use simpler model
netintel-ocr kg train-embeddings --model TransE --epochs 50

# Process without KG if not needed
netintel-ocr process pdf document.pdf --no-kg

MiniRAG Model Issues¶

ERROR: MiniRAG models not found
ERROR: MINIRAG_LLM environment variable not set

Solution:

# Set MiniRAG environment variables
export MINIRAG_LLM="ollama/gemma3:4b-it-qat"
export MINIRAG_EMBEDDING="ollama/qwen3-embedding:8b"
export MINIRAG_EMBEDDING_DIM="4096"

# Pull required models
ollama pull gemma3:4b-it-qat
ollama pull qwen3-embedding:8b

# Verify models are available
ollama list | grep -E "gemma3|qwen3"

Hybrid Retrieval Issues¶

ERROR: Strategy 'adaptive' failed
ERROR: RRF fusion error

Solution:

# Use specific strategy instead of adaptive
netintel-ocr kg hybrid-search "query" --strategy vector_first
netintel-ocr kg hybrid-search "query" --strategy graph_first

# Check both storage systems
netintel-ocr kg stats  # Check FalkorDB
netintel-ocr db stats  # Check Milvus

# Compare strategies to find working one
netintel-ocr kg compare-strategies "test query"

KG Query Issues¶

ERROR: Invalid Cypher syntax
ERROR: No results found

Solution:

# Check graph statistics first
netintel-ocr kg stats

# List all node types
netintel-ocr kg query "MATCH (n) RETURN DISTINCT labels(n)"

# Simple test query
netintel-ocr kg query "MATCH (n) RETURN n LIMIT 5"

# Use natural language instead
netintel-ocr kg rag-query "show all routers"

Configuration Template Issues¶

ERROR: Template not found
ERROR: Invalid configuration

Solution:

# List available templates
netintel-ocr config template list

# Apply template
netintel-ocr config init --template production

# View current config
netintel-ocr config show

# Validate configuration
netintel-ocr config validate

Profile Management Issues¶

ERROR: Profile not found

Solution:

# List profiles
netintel-ocr config profile list

# Create new profile
netintel-ocr config profile create production

# Switch profile
netintel-ocr config profile use production

# Show current profile
netintel-ocr config profile current

Environment Verification¶

Check System Compatibility¶

# Full system check
echo "OS: $(uname -s)"  # Must be Linux
echo "Arch: $(uname -m)"  # Should be x86_64
echo "Python: $(python3 --version)"  # Must be 3.11.x or 3.12.x
echo "Distro: $(lsb_release -d 2>/dev/null || cat /etc/os-release | grep PRETTY_NAME)"

# Expected output:
# OS: Linux
# Arch: x86_64  
# Python: Python 3.11.x (or 3.12.x)
# Distro: Ubuntu 20.04/22.04 or similar

Python Environment Check¶

# Verify Python installation
which python3.11 python3.12 2>/dev/null

# Check available Python versions
ls -la /usr/bin/python3*

# Verify pip version matches Python
pip --version  # Should show (python 3.11) or (python 3.12)

# Check virtual environment
python -c "import sys; print(f'Python: {sys.version}')"
python -c "import platform; print(f'Platform: {platform.platform()}')"

Knowledge Graph Deep Dive Troubleshooting¶

KG Performance Optimization¶

# Monitor KG processing performance
netintel-ocr kg stats --detailed

# Optimize for speed (fewer epochs, simpler model)
netintel-ocr process pdf document.pdf \
  --kg-model TransE \
  --kg-epochs 50 \
  --kg-batch-size 256

# Optimize for accuracy (more epochs, complex model)
netintel-ocr process pdf document.pdf \
  --kg-model ComplEx \
  --kg-epochs 200 \
  --kg-batch-size 128

# Skip KG for faster processing
netintel-ocr process pdf document.pdf --no-kg

KG Model Selection Guide¶

# For simple hierarchical networks
netintel-ocr kg train-embeddings --model TransE

# For complex relationships (DEFAULT)
netintel-ocr kg train-embeddings --model RotatE

# For symmetric relationships
netintel-ocr kg train-embeddings --model ComplEx

# For high accuracy (slower)
netintel-ocr kg train-embeddings --model ConvE

# View all available models
netintel-ocr kg train-embeddings --list-models

KG Visualization Issues¶

# If visualization fails
netintel-ocr kg visualize --method pca --dimensions 2

# Alternative visualization methods
netintel-ocr kg visualize --method umap
netintel-ocr kg visualize --method tsne --perplexity 30

# Save as image instead of HTML
netintel-ocr kg visualize --format png --output graph.png

KG Entity Analysis¶

# Find orphaned entities
netintel-ocr kg query "MATCH (n) WHERE NOT (n)--() RETURN n"

# Find most connected entities
netintel-ocr kg query "MATCH (n)-[r]-() RETURN n, count(r) as connections ORDER BY connections DESC LIMIT 10"

# Find specific entity types
netintel-ocr kg query "MATCH (n:Router) RETURN n"
netintel-ocr kg query "MATCH (n:Firewall) RETURN n"

Debugging Commands¶

Enable Debug Mode¶

# Full debug output (v0.1.17)
netintel-ocr --debug process pdf document.pdf

# Debug KG processing
netintel-ocr --debug kg process document.pdf

# Save debug logs
netintel-ocr --debug process pdf document.pdf --log-file debug.log

Test Components¶

# Test KG system
netintel-ocr kg check-requirements --test

# Test FalkorDB connection
netintel-ocr kg init --test-only

# Dry run without processing
netintel-ocr process pdf document.pdf --dry-run

Health Checks¶

# System health check
netintel-ocr system check

# Model availability
netintel-ocr model list

# Storage status
netintel-ocr system check

Log Analysis¶

Common Log Patterns¶

# Find errors in logs
grep ERROR netintel.log

# Find timeout issues
grep -i timeout netintel.log

# Find model issues
grep -E "(model|ollama)" netintel.log

# Find memory issues
grep -E "(memory|OOM|RAM)" netintel.log

Log Levels¶

# Verbose logging (v0.1.17)
netintel-ocr --debug process pdf document.pdf

# Only errors
netintel-ocr --log-level ERROR process pdf document.pdf

# Structured JSON logs
netintel-ocr --log-format json process pdf document.pdf

Recovery Procedures¶

Resume Failed Processing¶

# Save checkpoint (v0.1.17)
netintel-ocr process pdf document.pdf --checkpoint state.json

# Resume from checkpoint
netintel-ocr process pdf document.pdf --resume state.json

Rebuild Vector Index¶

# Rebuild corrupted index (v0.1.17)
netintel-ocr db compact --collection network_docs

# Verify index integrity
netintel-ocr db stats --collection network_docs

Reset Configuration¶

# Reset to defaults (v0.1.17)
netintel-ocr config init --force

# Regenerate project
netintel-ocr project init --force

Platform-Specific Issues¶

WSL2 (Windows Subsystem for Linux)¶

# If trying to run on Windows via WSL2
# Ensure WSL2 is properly configured
wsl --status
wsl --list --verbose

# Install Ubuntu 22.04 in WSL2
wsl --install -d Ubuntu-22.04

# Inside WSL2, install Python 3.11
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

# Install NetIntel-OCR in WSL2 environment
python3.11 -m pip install netintel-ocr

Docker on Non-Linux Systems¶

# Running via Docker on Windows/Mac
# Note: Performance may be degraded

# Use Linux container mode
docker run --platform linux/amd64 \
  -v $(pwd):/data \
  netintel-ocr:latest document.pdf

# Build for Linux platform
docker buildx build --platform linux/amd64 -t netintel-ocr:latest .

Common Linux Distribution Issues¶

Ubuntu/Debian¶

# Missing Python 3.11/3.12
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11-full

RHEL/CentOS/Rocky Linux¶

# Enable EPEL and install Python 3.11
sudo dnf install epel-release
sudo dnf install python3.11 python3.11-devel

Arch Linux¶

# Python versions available in standard repos
sudo pacman -S python  # Usually latest version

Knowledge Graph Quick Reference¶

Essential KG Environment Variables¶

# Required for KG operation
export OLLAMA_HOST="http://your-ollama-server:11434"
export FALKORDB_HOST="localhost"
export FALKORDB_PORT="6379"
export MINIRAG_LLM="ollama/gemma3:4b-it-qat"
export MINIRAG_EMBEDDING="ollama/qwen3-embedding:8b"

KG Processing Workflow¶

# 1. Check requirements
netintel-ocr kg check-requirements

# 2. Initialize system
netintel-ocr kg init

# 3. Process document with KG
netintel-ocr process pdf document.pdf  # KG enabled by default

# 4. Train embeddings (if needed)
netintel-ocr kg train-embeddings --model RotatE

# 5. Query the graph
netintel-ocr kg query "MATCH (n) RETURN n LIMIT 10"
netintel-ocr kg rag-query "show network topology"

# 6. Visualize results
netintel-ocr kg visualize --output graph.html

KG Troubleshooting Checklist¶

[ ] FalkorDB running and accessible
[ ] PyKEEN and torch installed
[ ] MiniRAG models pulled in Ollama
[ ] Environment variables set
[ ] Sufficient memory for embeddings (8GB+ recommended)
[ ] Graph initialized with kg init

Getting Help¶

Generate Diagnostic Report¶

# Full system diagnostic with KG info
netintel-ocr system diagnose --include-kg > report.txt

# KG-specific diagnostics
netintel-ocr kg stats --format json >> report.txt
netintel-ocr kg check-requirements --verbose >> report.txt

# Include system info
echo "=== System Info ===" >> report.txt
uname -a >> report.txt
python --version >> report.txt
lsb_release -a 2>/dev/null >> report.txt

Community Support¶

GitHub Issues: https://github.com/VisionMLNet/NetIntelOCR/issues
PyPI Package: https://pypi.org/project/netintel-ocr/
Documentation: https://visionml.net/docs
Discord: https://discord.gg/netintel-ocr

Include in Bug Reports¶

Operating System: uname -a (MUST be Linux)
Python version: python --version (MUST be 3.11.x or 3.12.x)
NetIntel-OCR version: netintel-ocr system version
Linux distribution: cat /etc/os-release
Ollama models: ollama list
Error messages and logs
Installation method (pip, Docker, source)
Sample PDF (if possible)

Next Steps¶

Multi-Model Guide - Optimize model selection
Performance Guide - Improve processing speed
API Integration - Programmatic troubleshooting