使用Apache PDFBox合并PDF遇Loop within object COSObject{2,0}错误求解决

错误原因 #

这个异常是因为你要合并的特定PDF文件内部存在循环引用的COS对象。COSObject是PDFBox对PDF底层对象的封装，当PDF内部的对象引用形成闭环（比如对象A引用对象B，对象B又反向引用对象A，或者更长的引用链形成循环），PDFBox在执行合并前的对象克隆操作时，PDFCloneUtility的checkForRecursion方法会检测到这种递归循环，从而抛出java.io.IOException: Loop within object异常。

这种循环引用通常是PDF生成工具的bug、文件损坏，或者某些特殊PDF结构（比如复杂的表单、注释）处理不当导致的。

解决办法 #

1. 预处理修复问题PDF #

优先尝试修复这个有问题的PDF，消除内部循环引用：

• 使用Adobe Acrobat打开该PDF，执行「文件」→「另存为」，选择PDF格式保存，Acrobat会自动修复PDF的内部结构，消除无效的循环引用。
• 用PDFBox自带的API修复：

import org.apache.pdfbox.pdmodel.PDDocument;
import java.io.File;

public class PDFFix {
    public static void main(String[] args) throws Exception {
        PDDocument doc = PDDocument.load(new File("problematic.pdf"));
        // 保存时会重新整理对象结构
        doc.save("fixed_problematic.pdf");
        doc.close();
    }
}

用修复后的文件参与合并即可。

2. 升级PDFBox版本 #

你使用的2.0.26是2021年的旧版本，后续的2.0.x维护版本（比如2.0.30+）或3.x正式版对循环引用的处理逻辑做了优化，部分场景下能自动兼容或修复这类问题，不会直接抛出异常。

3. 重新生成或转换问题PDF #

如果上述修复无效，说明该PDF的结构问题较严重：

• 尝试重新生成这个PDF文件（比如从原始文档重新导出），避免生成时出现循环引用。
• 用第三方工具将该PDF转换为PDF/A格式，再转回普通PDF，转换过程中会重构文件结构，消除循环引用。

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