Troubleshooting

Document Fails to Close — Memory Leak

Document implements AutoCloseable. Always use a try-with-resources block:

try (Document doc = new Document("input.pdf")) {
    // operations
} // doc.close() called automatically

OutOfMemoryError with Large Files

For large documents, enable disk buffering in PdfFileEditor:

PdfFileEditor editor = new PdfFileEditor();
editor.setUseDiskBuffer(true);
editor.concatenate(inputFiles, "output.pdf");

PdfFileSecurity: Incorrect Password

decryptFile(password) returns false if the provided password is incorrect. Always check the return value and handle the failure case:

try (PdfFileSecurity security = new PdfFileSecurity()) {
    security.setInputFile("encrypted.pdf");
    security.setOutputFile("decrypted.pdf");
    boolean ok = security.decryptFile("ownerPassword");
    if (!ok) {
        System.err.println("Decryption failed — verify the owner password.");
    }
}

PdfFileEditor: Null Arguments

PdfFileEditor.resizeContents() silently ignores null arguments rather than throwing. If the output document appears unchanged after resizeContents(), verify that the ContentsResizeParameters argument is not null and that the percentage values sum to exactly 100.

AESCipher: Wrong Key Length

AES requires keys of exactly 16, 24, or 32 bytes (128, 192, or 256 bits). Passing a key of incorrect length results in an exception from the underlying Java crypto provider.

Annotation Not Visible

If an annotation is added but does not appear in the viewer, check:

The annotation rectangle is within the page’s MediaBox
page.getAnnotations().add(annotation) was called after configuring all properties
The document was saved after adding the annotation