Troubleshooting

Common issues and possible solutions.

Installation Issues

Models Not Detected

For users: Models should be bundled with the application. If missing, re-download the application or ask your admin.

For developers:

• Verify models in resources/models/
• Check directory structure matches expected layout
• Ensure all files present (not just directories)
• Check file permissions
• Review application log

CUDA Issues

• Verify GPU is available
• Windows: ensure drivers are installed and up-to-date
• Check CUDA version compatibility (12.8 is supported)
• Check GPU memory availability

Runtime Issues

Application Won't Start

• Check application log
• Run from command line for errors
• Check system requirements (RAM, disk)

Slow Application start

• If your hardware is older you may experience a long application start

Jobs Fail to Start

• Check input files exist and are accessible
• Verify file permissions
• Check disk space
• Ensure models loaded
• Check GPU memory
• Review application log

Recognition Errors

• Check image quality (resolution, contrast)
• Verify correct job type (printed vs handwritten)
• Ensure correct language selected
• Try preprocessing images
• Check that model files are complete
• However, it may just be that the recognition methods currently implemented in Textum are not fit for your specific document style

Out of Memory

• Reduce max concurrent jobs (Settings)
• Process smaller batches
• Close other applications
• Check available RAM/VRAM
• Process images individually

User Interface Issues

Interface Not Responding

• Running a job may be resource hungry and slow the entire system down
• Reduce concurrent jobs
• Check system resources
• Restart application
• Review log

Performance Issues

Slow Processing

• Check GPU being used (not CPU) in the application log (can be opened form Settings)
• Verify if CUDA working
• Reduce image resolution if very large
• Process fewer pages at once
• Ensure models loaded properly
• Check system resources

High Memory Usage

• Reduce concurrent jobs
• Process smaller batches
• Close other applications
• Restart app
• Monitor memory usage in task manager

Export Issues

Export Fails

• Check disk space
• Verify write permissions
• Ensure job completed
• Check file path length and restrictions (Windows)
• Try different format
• Review log

Application Logs

Can be opened from the Settings.

Location: <working directory>/log.txt

Check logs for:

• Error messages
• Specific error codes
• Stack traces

System Information for Reporting

When reporting issues, include:

• Operating system and version
• Python version, if running from dev environment
• GPU model and drivers
• Textum version
• Relevant log file output
• Steps to reproduce

Quick Fixes

• Restart Application - Fixes many temporary issues
• Check Logs - Provides specific error details
• Verify Models - Ensure all are present and complete
• Check Resources - RAM, disk space, GPU memory