PyPDF2合并PDF出现KeyError: '/Root'错误的原因排查

问题场景 #

使用PyPDF2追加PDF文件时，大部分文件可正常合并，但部分特殊PDF会触发报错。将报错的PDF通过阅读器「另存为」同名文件后，程序即可正常运行，且保存前后PDF版本显示一致。

测试代码 #

from PyPDF2 import PdfMerger

attachment = 'C:/Users/John Doe/Desktop/test.pdf'

merger = PdfMerger()

merger.append(attachment)

报错信息 #

"C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\python.exe" "C:\Users\Joe Medina\Desktop\Joseph\Geoscope\Binders\tests.py"
incorrect startxref pointer(1)
Traceback (most recent call last):
  File "C:\Users\Joe Medina\Desktop\Joseph\Geoscope\Binders\tests.py", line 10, in <module>
    merger.append(attachment)
  File "C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\lib\site-packages\PyPDF2\_utils.py", line 390, in wrapper
    return func(*args, **kwargs)
  File "C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\lib\site-packages\PyPDF2\_merger.py", line 283, in append
    self.merge(len(self.pages), fileobj, outline_item, pages, import_outline)
  File "C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\lib\site-packages\PyPDF2\_utils.py", line 390, in wrapper
    return func(*args, **kwargs)
  File "C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\lib\site-packages\PyPDF2\_merger.py", line 174, in merge
    pages = (0, len(reader.pages))
  File "C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\lib\site-packages\PyPDF2\_page.py", line 2033, in __len__
    return self.length_function()
  File "C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\lib\site-packages\PyPDF2\_reader.py", line 446, in _get_num_pages
    self._flatten()
  File "C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\lib\site-packages\PyPDF2\_reader.py", line 1074, in _flatten
    catalog = self.trailer[TK.ROOT].get_object()
  File "C:\Users\Joe Medina\AppData\Local\Programs\Python\Python310\lib\site-packages\PyPDF2\generic\_data_structures.py", line 149, in __getitem__
    return dict.__getitem__(self, key).get_object()
KeyError: '/Root'

Process finished with exit code 1

成因分析 #

• 原PDF内部结构不规范/损坏：报错中的incorrect startxref pointer(1)表明PDF的交叉引用表指针错误，KeyError: '/Root'说明核心根目录对象无法被正确读取。PyPDF2对PDF规范的容错性较弱，而阅读器通常有更强的兼容机制，所以原文件能被阅读器打开，但无法被PyPDF2解析。
• 「另存为」的修复机制：PDF阅读器执行「另存为」时，会重新构建PDF的内部结构，包括修复交叉引用表、重建规范的根目录对象，同时清理冗余或损坏的数据块。虽然表面上版本不变，但内部结构已经符合严格的PDF规范，因此PyPDF2可以正常处理。
• 生成工具的问题：这类特殊PDF通常由不规范的生成工具产生，比如老旧的打印驱动、导出插件等，它们输出的PDF虽然能被阅读器兼容，但不符合标准格式，导致依赖规范结构的PyPDF2解析失败。

内容的提问来源于stack exchange，提问作者sacrishield