Troubleshooting

Most common cause: The file is open in another application (Acrobat, Edge, a browser tab) and is locked for exclusive read access. Close any other application that has the PDF open and try again.

Other things to check:

• Confirm the file extension is .pdf — PDF Auditor does not process .pdfa, .pdfx, or renamed files with non-standard extensions.
• Make sure you are dropping directly onto the drop zone area, not onto the title bar or toolbar.
• If the file is on a network share or external drive, copy it locally first — network latency can cause the file read to time out silently.
• Check that the PDF is not zero bytes. A corrupted or incomplete download will be rejected without an error message in some edge cases.

If none of the above apply, try using the CLI instead: pdf_auditor "C:\path\to\file.pdf" — it will print a specific error message if the file cannot be opened.

A visually correct PDF and an accessible PDF are not the same thing. The most common cause of an unexpectedly low score is a missing tag structure. PDFs exported from print-focused workflows (InDesign, Illustrator, older Word versions, virtual printer drivers like CutePDF) are often visually correct but contain no accessibility tags at all — they are essentially images of a document.

To understand which issues are driving the score, open the HTML report and look at the Critical findings first. Critical violations cost 15 points each. The two most common Critical findings are:

• Untagged PDF — no /MarkInfo dictionary. Fix: re-export from the source document with "Create tagged PDF" enabled, or use PDF Suite's tag editor.
• Missing document language — no /Lang entry in the PDF catalog. Fix: set the document language in Acrobat (File → Properties → Advanced) or re-export with language metadata enabled.

Fixing Critical findings first will raise the score the most per fix. Major findings (8 points each) and Minor findings (3 points each) can be addressed after Critical items are resolved.

Why this happens: PDF Auditor extracts foreground/background color pairs from the page content stream and computes WCAG 2.x relative luminance ratios. In some cases the extracted colors don't match what the eye sees:

• Transparency and blending: If text sits over a gradient, image, or blended background, the content stream may record the text color against a default white or black background rather than the actual rendered composite. The computed ratio will not match what you see on screen.
• Decorative graphics misidentified as text: Vector art rendered as text-stream operators (Tj, TJ) is treated as text by the parser. If a logo or icon is built this way, it may be flagged as a contrast failure.
• Scanned or image-only content: Raster images are not analyzed for contrast — but any real text objects on the same page are.

If you have confirmed a finding is a false positive for your specific use case, note it in your compliance documentation. WCAG 2.2 Success Criterion 1.4.3 provides an exception for decorative text and logotypes — auditors reviewing your remediation can apply that exception manually.

A future release of PDF Auditor will support per-finding suppression so known false positives can be excluded from the score without affecting other findings.

Report location: Both the HTML and JSON reports are written to the same folder as the input PDF by default. If the PDF was on a read-only volume (a network share, a CD/ISO, or a folder requiring admin access), the write will fail silently and no report file will be created.

If automatic browser open fails:

1. Navigate to the folder containing your PDF in File Explorer.
2. Look for a file named <your-pdf-name>_audit.html.
3. Double-click it to open it in your default browser.

To specify a custom output folder when using the CLI:

pdf_auditor "file.pdf" --output "C:\Reports"

If no report file exists at all, the audit may have encountered an error before completing. Run the CLI version with the same file — it will print any error messages to the terminal so you can diagnose the cause.

PDF Auditor cannot audit PDFs that are encrypted with an owner password or that have content extraction disabled. This is by design — extracting tag structure, font data, and page content requires reading the document structure, which encryption prevents.

Two types of PDF protection and what to do:

• Password to open (user password): Currently not supported. A future release will prompt for the document password before auditing.
• Permission restrictions (owner password) with no open password: The PDF opens without a password but has printing, copying, or content extraction disabled. PDF Auditor respects these permissions and will not extract content from restricted documents.

To audit a restricted PDF, remove the restrictions in Acrobat (File → Properties → Security → No Security), re-save, and audit the unrestricted copy. The accessibility of the document structure is not affected by removing owner restrictions.

The CLI is the same binary as the GUI — it just behaves differently when run from a terminal with arguments. The executable is not automatically added to your PATH on install.

Option 1 — Run by full path:

"C:\Program Files\Vexifa PDF Auditor\pdf_auditor.exe" "file.pdf"

Option 2 — Add to PATH permanently:

1. Open Settings → System → About → Advanced system settings → Environment Variables.
2. Under User variables, select Path and click Edit.
3. Add a new entry: C:\Program Files\Vexifa PDF Auditor
4. Click OK, close all dialogs, then open a new terminal window.

After adding to PATH, pdf_auditor --help should print the usage instructions.

Missing Visual C++ Redistributable: PDF Auditor requires the Microsoft Visual C++ 2015–2022 Redistributable (x64). If it's not installed you may see errors about VCRUNTIME140.dll or MSVCP140.dll.

1. Download the latest Visual C++ Redistributable from Microsoft's official site (search "Visual C++ Redistributable latest supported downloads").
2. Install the x64 version.
3. Restart your PC and try launching PDF Auditor again.

Windows version: PDF Auditor requires Windows 10 version 1903 or later. Windows 7, 8, and early Windows 10 builds are not supported.

If the app still won't launch after installing the redistributable, right-click the executable and choose Run as administrator once to confirm it's not a permissions issue. If it launches as admin but not normally, the install directory may have restricted permissions — reinstalling to a different location (e.g., your user Documents folder) will resolve this.

This is expected behavior for newly published applications that haven't yet built broad download history with Microsoft's SmartScreen reputation system. PDF Auditor is safe to run.

1. Click More info on the SmartScreen dialog.
2. Click Run anyway.

If you want to verify the file before running it, you can scan it via VirusTotal. The prompt will stop appearing automatically as more users download and run the application.

If your organization uses Windows Defender Application Control or a third-party allowlist policy, you will need to add PDF Auditor to the approved applications list through your IT administrator.