Troubleshooting
Start with the health check, not with a reinstall. Every item below is drawn from the installation guide, the shipped README troubleshooting table, the installer script and the verification report — and where the project files do not cover something, the page says so.
Step 1 — run the health check
- In the app: Health check in the sidebar → Run full test. Every line is a real operation — it opens files, converts, OCRs and measures — and ends with counts of passes and failures. The recorded result for this build is PASS 20, FAIL 0.
- Then press Export diagnostic report in the same screen. That report, plus the logs in
data\logs, is what a support request should carry. - From the portable package:
START-APPLICATION\RUN-HEALTH-CHECK.batwritesHealth_Report.htmleven if the interface will not open. - Quick UI fix to try first: press Ctrl+F5 in the app window to force-reload it.
Symptom table
| Symptom | What it means | What to do |
|---|---|---|
| “The bundled runtime folder is missing from this copy.” | The ZIP was not extracted in full, or Application\runtime\ was deleted. | Re-extract the whole archive; do not run files from inside the ZIP. |
| Nothing at all happens when you start | An antivirus or corporate download tool may have quarantined files under the runtime folder. | Check quarantine first, restore the files, start again. |
| First OCR run is slow | Model warm-up of roughly 5–8 seconds happens once per launch. | Nothing to fix — later calls are fast. |
| Port 8765 already busy | Something else (often a leftover instance) is listening on the app’s port. | Desktop mode picks the next free port automatically; the launcher is single-instance, so a second start brings the existing window forward. For web mode, pass --port 8766. |
| Word to PDF fails | Microsoft Word automation is unavailable on this machine. | Install Microsoft Word, or let the built-in fallback handle it (that path is Not Verified — check the output). |
| Nothing in the sidebar / a stale screen after an update | Cached interface files from the previous version. | Hard-refresh with Ctrl+Shift+R (or Ctrl+F5 in the app window). |
| Window doesn’t open | The desktop shell could not create its native window — the README names a missing WebView2 Runtime as a cause (preinstalled on Windows 11). | Use the browser route instead: the app falls back to your default browser, and both give the same application. |
Rows above are the troubleshooting entries of the shipped README and the installation guide, condensed. Rows about pip wheels and running from source only apply to a source checkout, where Python 3.10+ and pip install -r requirements.txt are required — packages carry their own runtime.
Nothing starts
- Read the reason the launcher prints — it does not fail silently.
- "The bundled runtime folder is missing from this copy." means an incomplete extraction: extract the whole archive again.
- Nothing at all happening usually means an antivirus or corporate tool quarantined files under Application\runtime — check there first.
- Confirm you are on a supported system: Windows 10 (1809 or newer) or Windows 11, 64-bit.
- If the interface opens but looks broken, Ctrl+F5 (app window) or Ctrl+Shift+R (browser) before anything else.
The window will not open
The app opens its own native window; if that cannot start, it opens in your default browser — both give you the same application, on the same local address, with your same data. Nothing is lost by using the browser route.
SmartScreen or antivirus warnings
The installer is not code-signed
The honest way to tell a genuine file from a tampered one is the hash:
- Compare the SHA-256 of your download with the value published on the Download Center (all three packages were hashed on 2026-10-16).
- On PowerShell:
Get-FileHash .\IrfanPDF_Setup_1.7.0.exe -Algorithm SHA256. - If the hash matches and security software still blocks the file, that is an environment decision the project files cannot override — the files it may quarantine are the bundled runtime’s, and the symptom is the startup row above.
Port already in use
The local server runs on 127.0.0.1 and normally on port 8765. The launcher is single-instance (mutex IrfanPDFSingleInstance), so starting the app again brings the existing window forward instead of fighting over the port; desktop mode picks the next free port on its own, and web mode can be pointed elsewhere with --port 8766. The regression runner refuses to test against a server that was already listening, precisely because a stale instance answers with yesterday’s code.
OCR or model problems
- OCR must run from the bundled runtime — the models ship with the package, so a partial extraction (see the startup rows) is the usual cause of OCR failing while the rest works.
- Only the English PP-OCRv5 model is bundled and verified. Other languages are Not Verified, and no Tesseract binary ships in any package.
- The first OCR call of a launch loads the models (roughly 5–8 seconds); later calls are fast.
- Digitally signed and encrypted PDFs are refused on purpose, with the reason given — that is design, not failure. See the OCR guide.
PDF association issues
The installer offers a task named “Open PDF files with Irfan PDF” and adds an “Open with Irfan PDF” verb. The registry entries are written as an offer — the installer’s own comment says user choice is recorded “so Windows knows the app was offered (not forced)” — and the association is never hijacked behind your back. If PDFs still open somewhere else: right-click a PDF → Open with → Irfan PDF, or re-run the installer and tick the association task. Whether your Windows build will let the default be changed, and what it does with a per-user association: Cannot verify from project files.
Still stuck
No support channel is published yet
data\logs, reproduction steps, Windows version and app version 1.7.0.Next: Installation · FAQ · Contact & support