Troubleshooting

Troubleshooting¶

This guide helps you resolve common issues with LDA. If you don't find your issue here, please check our GitHub Issues or ask in Discussions.

Installation Issues¶

Permission Denied¶

If you encounter permission errors during installation:

Solution 1: Install with --user flag

pip install --user lda-tool

Solution 2: Use a virtual environment

python -m venv lda-env
source lda-env/bin/activate  # On Windows: lda-env\Scripts\activate
pip install lda-tool

Python Version Error¶

LDA requires Python 3.8 or higher.

Check your Python version:

python --version

Solutions: 1. Upgrade Python to 3.8+ 2. Use pyenv to manage multiple Python versions:

pyenv install 3.10.0
pyenv local 3.10.0

Module Not Found¶

If LDA module is not found after installation:

Solution 1: Update pip and reinstall

python -m pip install --upgrade pip
pip install --force-reinstall lda-tool

Solution 2: Check Python path

which python
which pip
# Ensure they're from the same environment

Configuration Issues¶

Invalid Configuration File¶

Error: ConfigurationError: Invalid configuration file

Common causes: 1. YAML syntax errors 2. Missing required fields 3. Invalid field values

Debug steps:

# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('lda_config.yaml'))"

# Check configuration
lda validate config

Missing Placeholders¶

Error: MissingPlaceholderError: Missing placeholder values

Solution: Define all required placeholders

placeholders:
  project_code: "PROJ001"
  analyst: "john.doe"
  date: "2024-01-01"

File Tracking Issues¶

Hash Mismatch¶

Error: Hash mismatch for file: data.csv

Causes: 1. File modified outside LDA 2. Different line endings (Windows/Unix) 3. Encoding issues

Solutions:

# Update hash
lda track data.csv --force

# Check file encoding
file -i data.csv

# Fix line endings
dos2unix data.csv  # Unix
unix2dos data.csv  # Windows

Large File Tracking¶

Error: MemoryError when tracking large files

Solution: Configure chunk processing

performance:
  large_file_threshold: "100MB"
  chunk_size: "10MB"
  use_mmap: true

Permission Denied on Manifest¶

Error: PermissionError: [Errno 13] Permission denied: 'manifest.json'

Solutions:

# Fix permissions
chmod 644 manifest.json

# Check file ownership
ls -la manifest.json

# If locked by another process
lsof manifest.json

CLI Issues¶

Command Not Found¶

Error: bash: lda: command not found

Solutions:

Add to PATH:

echo $PATH
# Add Python scripts directory
export PATH="$HOME/.local/bin:$PATH"

Use full path:
```
python -m lda.cli
```
Reinstall with pipx:
```
pipx install lda-tool
```

Verbose Output Not Working¶

Issue: --verbose flag doesn't show detailed output

Solution: Set log level

export LDA_LOG_LEVEL=DEBUG
lda status --verbose

Performance Issues¶

Slow File Tracking¶

Symptoms: Tracking takes too long for many files

Solutions:

Enable parallel processing:

performance:
  parallel_tracking: true
  max_workers: 8

Use faster hash algorithm:

tracking:
  hash_algorithm: "xxhash"  # Faster than sha256

Exclude unnecessary files:

tracking:
  exclude_patterns:
    - "*.tmp"
    - "*.log"
    - "__pycache__/"

High Memory Usage¶

Solutions:

Limit memory usage:

performance:
  limits:
    max_memory: "2GB"

Process files in batches:
```
performance:
  batch_size: 100
```

Integration Issues¶

Git Integration¶

Issue: Git commits fail after LDA tracking

Solution: Configure git hooks properly

# Install LDA git hooks
lda git install-hooks

# Or manually create pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
lda validate --strict
EOF
chmod +x .git/hooks/pre-commit

Database Connection¶

Error: DatabaseError: could not connect to server

Debug steps:

# Test connection
psql -h localhost -U lda_user -d lda_db

# Check environment variables
echo $DATABASE_URL

# Verify configuration
lda debug db-test

Platform-Specific Issues¶

Windows¶

Path Separators¶

Issue: Incorrect path separators

Solution: Use forward slashes or raw strings

# Good
root_folder: "C:/Projects/LDA"
# Or
root_folder: "C:\\Projects\\LDA"

Line Endings¶

Issue: CRLF vs LF issues

Solution: Configure Git

git config core.autocrlf true

macOS¶

SSL Certificate Error¶

Error: SSL: CERTIFICATE_VERIFY_FAILED

Solution:

# Install certificates
cd /Applications/Python\ 3.x/
./Install\ Certificates.command

Linux¶

Missing Dependencies¶

Error: ImportError: libpython3.8.so.1.0

Solution:

# Ubuntu/Debian
sudo apt-get install python3.8-dev

# Fedora/RHEL
sudo dnf install python38-devel

Debug Mode¶

Enable debug mode for detailed diagnostics:

# Set debug environment variable
export LDA_DEBUG=1

# Run with debug output
lda --debug status

# Generate debug report
lda debug report --output debug_report.txt

Common Error Messages¶

`FileNotFoundError`¶

Possible causes: - File doesn't exist - Wrong working directory - Incorrect path in config

Debug:

pwd  # Check current directory
ls -la  # List files
lda debug paths  # Show LDA paths

`JSONDecodeError`¶

Possible causes: - Corrupted manifest.json - Invalid JSON syntax

Fix:

# Backup and recreate
cp manifest.json manifest.backup
lda repair manifest

`TimeoutError`¶

Possible causes: - Network issues - Large file operations - Slow external services

Solution:

performance:
  timeouts:
    file_operation: 300  # seconds
    network_request: 60

Getting Help¶

If you're still experiencing issues:

Search existing issues:

# Search GitHub issues
https://github.com/drpedapati/LDA/issues?q=is:issue+error

Create detailed bug report:

# Generate diagnostic info
lda debug report --full > debug_info.txt

Ask for help:
GitHub Discussions
Stack Overflow
Report new issue:
Use issue template
Include debug report
Provide minimal example

Troubleshooting