Common Issues

Common Issues

This page covers the most common early problems. Use it as a fast triage page, then move into the main repo docs for deeper debugging.

The App Will Not Start

If you are running from source:

• confirm the virtual environment was created cleanly
• upgrade pip
• reinstall requirements.txt
• run the source launcher again

Useful commands:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\scripts\Run-App.ps1

If you are running a packaged build:

• make sure you extracted the whole release folder
• do not launch only the .exe without its bundled files
• unzip to a normal writable location

Drag and Drop Or Tkinter Problems

This is usually a local environment or packaged-runtime problem, not an estimate parsing problem.

Read:

• Repository README quick start
• Windows EXE build and packaging notes

The PDF Converts But The Parse Looks Thin Or Empty

Common reasons:

• the PDF is scanned and OCR quality is poor
• the packet includes guide pages or non-estimate pages
• the carrier layout is not yet well-covered
• text extraction succeeded technically but produced broken or fragmented text

Check:

• the in-app warnings
• the generated *.canonical.json
• the readable *.esx.xml

Scanned PDFs

Scanned PDFs are supported on a best-effort basis through local OCR.

What to expect:

• better than raw text extraction on image-heavy packets
• still sensitive to skew, blur, page quality, and unusual layouts
• not all scans will produce line-item-quality output

ESX Output Does Not Import Or Looks Wrong

First determine whether the problem started in parsing or export.

Look at:

• *.canonical.json
• *.esx.xml

If the canonical file already looks wrong, focus on parsing.

If the canonical file looks reasonable but the XML/package looks wrong, focus on export or mapping.

Where The Logs Are

Source-mode default log:

• logs\pdf_to_esx_agent.log

Packaged-build default log:

• %LOCALAPPDATA%\PDF-TO-ESX-Agent\logs\pdf_to_esx_agent.log

Best Deep-Dive Docs

• Debugging guide
• Common failure patterns
• Known limitations
• Packaged app validation
• Open an issue