Troubleshooting
This page collects fixes for the most common issues encountered across Aspose.PDF FOSS for TypeScript’s signing, annotation, redaction, drawing, conversion, and text APIs.
Async Methods (Sign, Certify, VerifySignatures) Appear to Do Nothing
Document.Sign(), Document.Certify(), and Document.VerifySignatures()
all return a Promise. Calling one without await lets execution
continue immediately — a following doc.WriteTo() or doc.Save() can run
before the signature has actually been written, and a following
console.log() on the verification result logs an unresolved Promise
instead of the SignatureReport[] array:
// Wrong — WriteTo can race ahead of Sign:
approving.Sign(identity, opts);
approving.WriteTo('signed.pdf');
// Correct:
await approving.Sign(identity, opts);
approving.WriteTo('signed.pdf');See the Security guide for the full certify-then-sign flow.
SearchAnnotationText() and SearchAnnotations() Return Different Results for the Same Text
These two search methods are disjoint in both directions on the same
page. SearchAnnotationText() matches literal annotation metadata
(/Contents, /T, /Subj); SearchAnnotations() matches the rendered
text drawn by a markup annotation’s own appearance (for example a
FreeText body). A value stored only in /Contents is found by one and
missed by the other:
const metadataHits = page.SearchAnnotationText('confidential'); // matches /Contents, /T, /Subj
const renderedHits = page.SearchAnnotations('confidential'); // matches rendered markup text
Neither method searches ordinary page text — use Page.GetText() or
Page.Search() for that. See the
Annotations
guide for the full annotation API.
A Redaction Mark Alone Does Not Remove Content
Page.AddRedact() only draws a RedactAnnotation over a region — the
content underneath is untouched and still copy-selectable until
Page.ApplyRedactions() runs and destructively rewrites the content
stream. Marks added after ApplyRedactions() has already run stay
unapplied indefinitely:
page.AddRedact({ rect: [216, 548, 460, 566], fill: [0, 0, 0], overlayText: '[REDACTED]' });
page.ApplyRedactions(); // only now is the content actually destroyed
See the Redaction guide for mark-vs-apply details and text-search redaction.
PageGraphics Drawing Calls Never Appear on the Page
Page.Graphics() returns a PageGraphics that buffers every
moveTo()/rect()/circle()/stroke()/fill() call until apply()
commits them to the page. A sequence missing its apply() call draws
nothing:
const g = page.Graphics();
g.setStrokeColor([0.2, 0.2, 0.2]).setLineWidth(1).rect(80, 300, 200, 100).stroke();
g.apply(); // required — nothing above is visible without this call
See the Images guide for the full drawing and optional-content-layer API.
Document.ToHtml() and Hand-Tagging Both Depend on a Structure Tree
Semantic-mode Document.ToHtml() reflows content by walking the
structure tree; on an untagged document it silently falls back to a
heuristic body and the export loses its heading structure. The same tree
is what hand-authored tagging (StructTreeRoot.Append() /
StructElement.MarkContent()) writes into and what
Document.GetStructTree() returns — call Document.CreateStructTree() or
Document.AutoTag() before either:
const root = doc.GetStructTree();
if (!root) throw new Error('document is not tagged yet');See the Conversion and Structure guides for the export and tagging APIs respectively.
AddTextBlock() Silently Clips Text at Its Bounding Rectangle
Page.AddTextBlock(text, rect, options) wraps text inside rect and
returns whatever did not fit (or null if everything fit) — it does not
grow the rectangle or throw when content overflows. A return value that
is ignored means the overflow text is simply never drawn:
const rest = page.AddTextBlock(longText, [72, 600, 200, 150], { fontSize: 11 });
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // route the overflow somewhere
See the Text guide for the full text-placement and extraction API.