Hello Markus,
we can look at making PDFBox handling this. OTOH the file itself is not
spec compliant. Do you know what tool has generated this PDF?.
"... Each entry shall be a text string representing the on state of the
corresponding widget annotation.". We can look at handling that
gracefully.
When creating a ticket can we add the file to the ticket?
BTW: the workaround you documented looks fine for now
BR
Maruan
Am Dienstag, dem 28.04.2026 um 10:12 +0000 schrieb Markus Mensinger via
users:
>
>
>
> Hi PdfBox Team,
>
> we have a problem with a customer document.
> Download:
> pdf-Symbol form_with_checkbox.pdf
> Link valid until 08.05.
>
> Here is a bug report generated with Claude Sonnet.
>
>
> Component: PDFBox - Interactive Forms (AcroForm)
> Affects Version: 3.0.7
> Type: Bug
>
>
> SUMMARY
>
> When a checkbox field in an AcroForm PDF contains an empty /Opt array
> (/Opt [])
> in its field dictionary, calling PDCheckBox.setValue("Yes") throws an
> IllegalArgumentException, even though "Yes" is a perfectly valid
> export value
> defined by the field's appearance states.
>
> The same field can be checked and unchecked without any error using
> Adobe Acrobat
> products (Acrobat Reader, Acrobat Pro), which treat the empty /Opt
> array as if it
> were absent. This confirms that the PDF is valid and the issue is
> specific to
> PDFBox's validation logic.
>
>
> ERROR MESSAGE
>
> java.lang.IllegalArgumentException: value 'Yes' is not a valid option
> for the field Check_Info_Post_andere, valid values are: [] and Off
>
>
> ROOT CAUSE
>
> The validation in PDCheckBox.setValue() checks the /Opt array when it
> is present.
> If the array exists but is empty, all non-"Off" values are rejected -
> including the
> export value "Yes" that is defined in the field's appearance
> dictionary (/AP).
> The empty /Opt array should either be ignored or treated as absent -
> which is
> exactly what Adobe Acrobat does.
>
>
> STEPS TO REPRODUCE
>
> import org.apache.pdfbox.Loader;
> import org.apache.pdfbox.cos.COSArray;
> import org.apache.pdfbox.cos.COSName;
> import org.apache.pdfbox.pdmodel.PDDocument;
> import org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox;
> import org.apache.pdfbox.pdmodel.interactive.form.PDField;
>
> import java.io.File;
>
> public class CheckBoxBugDemo {
>
> public static void main(String[] args) {
> try (PDDocument doc = Loader.loadPDF(new
> File("form_with_checkbox.pdf"))) {
>
> PDField field = doc.getDocumentCatalog()
> .getAcroForm()
> .getField("Check_Info_Post_andere");
>
> System.out.println("Field type : " +
> field.getFieldType());
> System.out.println("/Opt entry : " +
> field.getCOSObject().getItem(COSName.OPT)); //
> prints: COSArray{}
>
> // Workaround: manually remove the empty /Opt array
> before setting value
> COSArray opt = (COSArray)
> field.getCOSObject().getDictionaryObject(COSName.OPT);
> if (opt != null && opt.size() == 0) {
> field.getCOSObject().removeItem(COSName.OPT);
> System.out.println("/Opt removed (was empty)");
> }
>
> // Without the workaround above, this line throws
> IllegalArgumentException:
> // "value 'Yes' is not a valid option ... valid values
> are: [] and Off"
> ((PDCheckBox) field).setValue("Yes");
>
> System.out.println("Value set successfully: " +
> ((PDCheckBox) field).getValue());
>
> } catch (Exception e) {
> e.printStackTrace();
> }
> }
> }
>
>
> EXPECTED BEHAVIOR
>
> An empty /Opt array should be treated the same as a missing /Opt
> entry. The value
> "Yes" (or any export value present in the field's appearance states)
> should be
> accepted. This is consistent with how Adobe Acrobat Reader and
> Acrobat Pro handle
> this case.
>
>
> ACTUAL BEHAVIOR
>
> PDCheckBox.setValue("Yes") throws IllegalArgumentException because
> the empty /Opt
> array causes the valid-options check to return an empty list, which
> excludes "Yes".
>
>
> WORKAROUND
>
> Remove the empty /Opt entry from the field dictionary before calling
> setValue():
>
> COSArray opt = (COSArray)
> field.getCOSObject().getDictionaryObject(COSName.OPT);
> if (opt != null && opt.size() == 0) {
> field.getCOSObject().removeItem(COSName.OPT);
> }
> ((PDCheckBox) field).setValue("Yes");
>
>
> SUGGESTED FIX
>
> In the PDFBox source, the method that validates allowed values for a
> checkbox should
> skip or ignore the /Opt array when it is present but empty (size() ==
> 0), bringing
> the behavior in line with Adobe Acrobat.
>
>
> Kind regards
> Markus
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
