Troubleshooting

Common issues and solutions when working with Aspose.PDF FOSS for .NET.

Problem	Cause	Solution
`Document.Open` throws on a valid PDF	File is password-protected	Supply the password in the constructor
Out of memory on large PDFs	Entire file loaded into byte array	Process pages individually or use streaming
`Pages[0]` throws index error	Pages use 1-based indexing	Use `Pages[1]` for the first page

Problem	Cause	Solution
Annotation not visible after save	Rectangle has zero area or is outside page bounds	Verify coordinates fall within the page `MediaBox`
`LinkAnnotation.Uri` returns null	Link uses a GoTo or JavaScript action	Resolve via `PdfAction.Create` and check `ActionType`
`Flatten()` throws	Annotation missing `/P` (page) reference	Ensure annotation was added through `Page.Annotations`

Problem	Cause	Solution
Extracted text is garbled	Non-standard encoding or CID font mapping	Check font embedding; scanned PDFs may need OCR
No text fragments found	Page content is a raster image	Use OCR before text extraction
Regex returns no matches	PDF text layout inserts whitespace	Use a looser pattern or normalize whitespace

Problem	Cause	Solution
Rendered image is blurry	Resolution too low	Increase DPI in `Resolution` constructor
HTML output missing images	External image paths not configured	Use `HtmlSaveOptions` with embedded images
PDF/A conversion removes annotations	Target profile disallows annotations	Use PDF/A-2 or PDF/A-3

Problem	Cause	Solution
Field value is empty	Field has no `/V` entry	Check `field.Value` is not null
`FillField` has no effect	Field name mismatch	Use `Form.FieldNames` to list available names
ExportToJson produces empty output	Widget annotation not correctly cast	Verify the annotation is a `WidgetAnnotation`

Troubleshooting

See Also