[Kylinny]

Summary

Fixes #4829 by making the default docling-parse backend identify encrypted PDFs instead of reporting the same generic load error used for corrupt files.

When docling-parse fails to load a PDF, the backend now asks PDFium to classify the same load failure and checks PDFium's FPDF_ERR_PASSWORD error code. This is a structural PDF parse, not a byte-pattern or trailer-location heuristic, so it also covers linearized PDFs and cross-reference streams. The original docling-parse exception remains the chained cause.

The probe runs only on docling-parse's failure path. docling installs both PDF backends, while users who install only the format-pdf-docling extra may not have PDFium; in that case the backend preserves the original generic error rather than guessing from the bytes.

Tests

• Both PDF backends with no password and a wrong password.
• A valid encrypted PDF with more than 16 KiB appended after its normal trailer, proving detection does not depend on /Encrypt being inside a fixed tail window.
• The stream-position invariant for BytesIO inputs.
• Existing corrupt, non-encrypted PDFs retain the original load error.

The parser-native long-term fix is tracked in docling-project/docling-parse#414. Once a released docling-parse exposes PdfPasswordError, this fallback can be replaced directly with that exception type.

Fixes #4829.

[github-actions]

✅ DCO Check Passed

Thanks @Kylinny, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit 48156483dd. The analysis read the diff only. It did not run code from this pull request.

Warning

The AI analysis did not finish. Only the deterministic checks are shown.

CI safety: not assessed.

Possibly related pull requests

PR	State	Signal	Assessment
#3757	merged	referenced as #3757; also references issue #1920	not assessed

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[github-actions]

AI first review (advisory): no blocker found

This review covers the full diff at 05499893bd. It read the code and did not run it.

The new probe only looks at the last 8 KiB of the file for /Encrypt. Encrypted PDFs where that entry is not in the last 8 KiB will still get the generic load error, and the PR does not say so. The reviewer must decide whether this coverage limit is acceptable, and whether the test PDF really shows the fix.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[github-actions]

question: Tail-only probe can miss /Encrypt in valid encrypted PDFs

_pdf_trailer_indicates_encryption() reads only the last 8 KiB (_ENCRYPTION_PROBE_TAIL_BYTES). In two valid PDF layouts the /Encrypt entry may be outside that window:

• Linearized PDFs. The first-page trailer near the start of the file carries /Encrypt. As I recall the spec, the trailer at the end of the file holds only /Size. Please check this against ISO 32000 Annex F.
• PDFs with cross-reference streams. /Encrypt sits in the stream dictionary, which comes before the stream data. For a large document, the stream data can be bigger than 8 KiB. Then the dictionary is outside the tail window.

In both cases the probe returns False. The user gets the old generic docling-parse could not load document ... message, the same defect as #4829.

Please ask the author two things:

1. Which PDF layouts did they test? The only fixture is tests/data/pdf_password/sources/2206.01062_pg3.pdf, a single-page file.
2. If these layouts are out of scope, state the limit in the docstring or the PR description.

[PeterStaar-IBM]

I dont think you can identify if it is password protected by a regex, we need to do this more properly.

[Kylinny]

Agreed. I replaced the regex/trailer scan entirely in 4815648. The failure is now classified by loading the same input with PDFium and checking its structured FPDF_ERR_PASSWORD error code. The probe runs only after docling-parse fails, preserves BytesIO position, and falls back to the original generic error when the optional PDFium backend is unavailable rather than guessing. I also added a regression with more than 16 KiB after the encrypted PDF trailer, which the former tail scan could not detect. The parser-native exception in docling-parse#414 remains the cleaner long-term path once released.

[codecov]

Codecov Report

❌ Patch coverage is 84.61538% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/backend/docling_parse_backend.py	84.61%	3 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[PeterStaar-IBM]

I dont think you can identify if it is password protected by a regex, we need to do this more properly.