ข้อผิดพลาดการเรนเดอร์และ I/O

ขอบเขต

รายการเหล่านี้ครอบคลุม exception การเรนเดอร์และ input/output (I/O) ที่ยกขึ้นขณะ ไปป์ไลน์ HTML จัดวางเนื้อหา ตัว resolver แบบ paged-media กำหนด เรขาคณิตหน้า ตัว shape ข้อความประมวลผล script ที่ซับซ้อน ขั้น typography ตัด บรรทัด ตัวเขียน serialize เอกสาร ตัวอ่านแยกวิเคราะห์ PDF ที่มีอยู่ และ ขั้นข้อมูลเมตาอ่านแพ็กเก็ต Extensible Metadata Platform (XMP)

ลำดับชั้นฐานสองชุดปรากฏด้านล่าง และความแตกต่างกำกับว่าข้อมูลวินิจฉัย ใดที่คุณอ่านได้หลัง catch:

NextPdfException นำ ContextAwareExceptionInterface::getContext(): array ไปใช้ การนำไปใช้ฐาน คืนอาร์เรย์ว่าง ซับคลาสพกพาคีย์แบบมีโครงสร้าง เฉพาะเมื่อมันเขียนทับ getContext() ซับคลาสที่ไม่เขียนทับมัน ยังเปิดเผยข้อมูลผ่านพร็อพเพอร์ตี public readonly
คลาสหลายตัวที่นี่สืบทอดจาก RuntimeException ของ PHP โดยตรง มันไม่ใช่ context-aware และไม่มีเมธอด getContext() ให้อ่าน getMessage() และพร็อพเพอร์ตี public ใดๆ แทน

แต่ละรายการระบุชื่อคลาสที่แน่นอน เงื่อนไขการกระตุ้น คีย์ context หรือ พร็อพเพอร์ตี public ที่มันพกพา และเส้นทางการกู้คืน

เลย์เอาต์ HTML และสื่อแบบแบ่งหน้า

`UnsplittableContentException`

ถูกยกเมื่อใด เอนจินจัดวาง HTML ยกสิ่งนี้เมื่อเนื้อหาที่ทำเครื่องหมาย break-inside: avoid (เซลล์ตารางที่มีข้อจำกัด break เป็น Avoid) มี ความสูงที่วัดได้เกินความสูงที่ใช้ได้ของหน้าเดียว เอนจิน ไม่อาจสนองทั้งข้อจำกัด avoid-break และขอบเขตหน้าได้ มันจึง ล้มเหลวแทนการล้นอย่างเงียบๆ
Carried data สืบทอดจาก NextPdfException แต่ไม่เขียนทับ getContext() ดังนั้น getContext() คืนอาร์เรย์ว่าง ข้อมูลวินิจฉัย อยู่บนพร็อพเพอร์ตี public readonly: gridRow (int), gridCol (int), contentHeight (float, points) และ pageHeight (float, points) ข้อความ ระบุชื่อพิกัดเซลล์และความสูงทั้งสอง
Recovery ลบข้อจำกัด break-inside: avoid บนเซลล์ที่ เป็นปัญหา ลดเนื้อหาของเซลล์ให้พอดีหนึ่งหน้า หรือเพิ่มขนาดหน้า หรือลด margin เพื่อให้ความสูงที่ใช้ได้รองรับเนื้อหา

`BudgetExceededException`

ถูกยกเมื่อใด primitive การจัดวางแบบ retained-mode ยกสิ่งนี้เมื่อหนึ่งใน สี่ tier งบประมาณทรัพยากรที่นิยามใน architecture decision record ADR-020 ถูกฝ่าฝืน และผู้เรียกเลือกความล้มเหลวแบบ hard แทนการ fallback แบบ soft เส้นทางเริ่มต้นไม่ยก: ContainerLayout::acceptChild() คืน false ผู้เรียก fall back ไปยัง block layout และมีคำเตือนถูก ปล่อย exception ถูกสงวนไว้สำหรับการตรวจสอบยืนยันที่เวลากำหนดค่าและสำหรับ test ที่ assert tuple การฝ่าฝืนที่แน่นอน tier คือ per-child (สตรีม child ที่จับได้เกิน cap ของมัน) per-container (งบประมาณจำนวน node Tier 1) per-document (งบประมาณ layout-pass หรือ nesting-depth) และ global (เพดาน peak resident-set-size ทั่ว SDK ที่ 256 MB)
Carried data เขียนทับ getContext() ซึ่งคืนรูปทรงแปดคีย์ที่เสถียร ที่บริโภคโดยเครื่องมือ application performance monitoring (APM): budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize, และ processedItemCount สี่คีย์แรก เป็นเซ็ตย่อย v1.0.0 ดั้งเดิมและถูกเติมเสมอ สี่คีย์หลัง ตั้งค่าเริ่มต้นเป็น null หรือ 0 เมื่อ constructor ถูกเรียกโดยไม่มีมัน getCausalWarningCode() map tuple (tier, container-type) ไปยัง WarningCode ที่เส้นทาง soft-fallback จะปล่อย
Recovery สำหรับการฝ่าฝืนการกำหนดค่า ให้ลดค่าที่ร้องขอกลับเข้า envelope ที่บันทึกไว้ (ตัวอย่างเช่น งบประมาณ retained node ยอมรับ 5,000 ถึง 100,000 ผ่าน Config::withRetainedNodeBudget()) สำหรับการฝ่าฝืนเนื้อหา ให้ ลดการ nesting ของ container หรือจำนวน node หรือพึ่ง soft-fallback เริ่มต้นไปยัง block layout แทนการเลือกพื้นผิว hard-failure

`UnsupportedNamedPageException`

ถูกยกเมื่อใด ขั้น paged-media ยกสิ่งนี้ ล้มเหลวแบบปิด เมื่อ เอกสารประกาศกฎ @page <ident> { … } แบบมีชื่อ (ผูกกับเนื้อหาผ่าน พร็อพเพอร์ตี page: <ident>) named page จาก CSS Paged Media Level 3 §3.4 และ Level 4 §3.2 — รวมถึง pseudo-class :first, :left, :right, และ :blank และ override size: และ rotate: แบบมีชื่อ — ถูกแยกวิเคราะห์แต่ไม่มี เส้นทางการจัดวางจริงบริโภคมัน เอนจินปฏิเสธแทนการปล่อย การแบ่งหน้าเริ่มต้นที่ผิดอย่างเงียบๆ ที่การทิ้งกฎจะสร้างขึ้น
Carried data เขียนทับ getContext() ซึ่งคืน page_names (รายการ ident ที่แตกต่างกันซึ่งทำให้เกิดความล้มเหลว ตามลำดับ source), has_size_override (bool), has_rotate_override (bool), และ has_pseudo_classes (bool) ค่าเดียวกันถูกเปิดเผยบนพร็อพเพอร์ตี public pageNames, hasSizeOverride, hasRotateOverride, และ hasPseudoClasses
Recovery ลบกฎ @page <ident> แบบมีชื่อและการผูก page: <ident> ใดๆ และแสดงเรขาคณิตที่ตั้งใจผ่านกฎ @page { … } แบบไม่มีชื่อที่รองรับ และรูปแบบ pseudo-class ของมัน หรือ pin ไปยังรีลีส ในอนาคตที่มีการรองรับการจัดวาง named-page เต็มรูปแบบ

การจัดวางตัวอักษรและการจัดรูปข้อความ

`IcuRequirementException`

ถูกยกเมื่อใด การแบ่งส่วนข้อความยกสิ่งนี้เมื่อมันต้องการตัว iterator การตัดบรรทัดของ International Components for Unicode (ICU) แต่ นโยบาย require-ICU ทำงานอยู่ (NEXTPDF_REQUIRE_ICU=1) ขณะที่ส่วนขยาย ext-intl และ IntlBreakIterator ไม่พร้อมใช้งาน
Carried data สืบทอดจาก RuntimeException โดยตรง มันจึงไม่ใช่ context-aware และไม่มี getContext() มันเป็นการ refine ที่เข้มงวดของ exception ทั่วไปที่เส้นทางโค้ดเดียวกันเคยยกขึ้น ตัวจัดการ catch (\RuntimeException) ที่มีอยู่จึงยังทำงานต่อไป
Recovery ติดตั้งและเปิด ext-intl เพื่อให้ตัว ICU break iterator พร้อมใช้งาน หรือยกเลิกการตั้ง NEXTPDF_REQUIRE_ICU เพื่อ fall back ไปยังตัว segmenter ที่ไม่ใช่ ICU เมื่อนโยบาย require-ICU ไม่ใช่สิ่งบังคับ

`ScriptShaperException`

ถูกยกเมื่อใด นี่คือ exception ฐานสำหรับ service provider interface (SPI) ของการ shape script มันไม่ถูกยกโดยตรงในวันนี้ ซับชนิดที่เป็นรูปธรรม ถูกยกแทน จับชนิดนี้เพื่อจัดการความล้มเหลวการ shape ใดๆ ในที่เดียว
Carried data สืบทอดจาก RuntimeException โดยตรง ไม่ใช่ context-aware ไม่มี getContext()
Recovery แยกกิ่งบนซับชนิดที่เป็นรูปธรรม ดู NotYetImplementedException ด้านล่างสำหรับซับชนิดเดียวที่จัดส่งในรีลีสปัจจุบัน

`NotYetImplementedException`

ถูกยกเมื่อใด ตัว shape script แบบ placeholder ทุกตัวยกสิ่งนี้จาก body shape() ของมันสำหรับ script ที่การ shape ที่เป็นรูปธรรมถูกเลื่อน (Mongolian และ Tibetan) seam ของ SPI การ shape พร้อมเชิงสถาปัตยกรรม แต่การ shape จริงยัง รอ fixture ที่ตรวจสอบยืนยันโดยเจ้าของภาษา การยก exception แทน no-op เงียบๆ ปรากฏการเชื่อมต่อในการใช้งานจริงโดยอุบัติเหตุที่รันไทม์แทน การปล่อยข้อความที่ยังไม่ถูก shape ลงใน PDF ที่อ้างการช่วยการเข้าถึงที่แท็ก
Carried data สืบทอดจาก ScriptShaperException (และจึงเป็น RuntimeException) มันจึงไม่ใช่ context-aware และไม่มี getContext() ข้อมูลวินิจฉัยอยู่บนพร็อพเพอร์ตี public readonly: bcp47LanguageTag (BCP-47 tag ของ run เช่น mn-Mong หรือ bo-Tibt) และ missingCapability (ความสามารถที่เป็นรูปธรรมที่การนำไปใช้ขาด) ข้อความรวมทั้งสอง
Recovery อย่าส่ง run ใน script ที่ยังไม่ถูกนำไปใช้ผ่าน shaper ในการใช้งานจริง ตรวจจับ language tag ที่ต้นทางและ fall back ไปยัง เส้นทางการเรนเดอร์ที่แตกต่างหรือ pin ไปยังรีลีสในอนาคตที่มีการ shape สำหรับ script ที่ได้รับผลกระทบ

โปรไฟล์เอาต์พุตของ writer และการเข้ารหัสลับ

`Pdf14FeatureRejectedException`

ถูกยกเมื่อใด ตัวเขียนยกสิ่งนี้เมื่อเอกสารมี คุณสมบัติที่ต้องห้ามภายใต้ PDF 1.4 output profile (ISO 19005-1:2005 / PDF/A-1) ซึ่งห้าม construct ที่นำเข้ามาใน PDF เวอร์ชันหลังกว่า
Carried data สืบทอดจาก NextPdfException แต่ไม่เขียนทับ getContext() ดังนั้น getContext() คืนอาร์เรย์ว่าง ข้อมูลวินิจฉัย อยู่บนพร็อพเพอร์ตี public readonly: feature (ชื่อคุณสมบัติที่ถูกปฏิเสธ), reason (เหตุที่มันต้องห้าม) และ isoClause (การอ้างอิง ISO clause) ข้อความรวมทั้งสาม
Recovery ลบหรือแทนที่คุณสมบัติที่ถูกปฏิเสธด้วยสิ่งเทียบเท่าที่ เข้ากันได้กับ PDF 1.4 หรือมุ่งไปยัง output profile ที่สูงกว่าซึ่งอนุญาตคุณสมบัติ

`Pdf20FeatureRejectedException`

ถูกยกเมื่อใด ตัวเขียนยกสิ่งนี้เมื่อเอกสารมี คุณสมบัติที่ต้องห้ามภายใต้ strict PDF 2.0 output profile ISO 32000-2:2020 เลิกใช้ construct ที่ PDF 1.7 ยังอนุญาต — โดยเฉพาะอย่างยิ่ง ฟอนต์ Standard 14 Type 1 (§9.6.2) ซึ่งต้องถูกฝังในเอกสาร PDF 2.0 ที่สอดคล้อง
Carried data รูปทรงเดียวกับ Pdf14FeatureRejectedException: สืบทอดจาก NextPdfException ไม่เขียนทับ getContext() (คืนอาร์เรย์ว่าง) และเปิดเผย feature, reason, และ isoClause เป็นพร็อพเพอร์ตี public readonly
Recovery แก้คุณสมบัติที่ถูกปฏิเสธ — ตัวอย่างเช่น ฝังฟอนต์ base 14 — หรือใช้ทางออกที่บันทึกไว้เมื่อมี (สำหรับฟอนต์ base 14 ที่ไม่ฝัง Document::allowNonEmbeddedBase14())

`PublicKeyEncryptionUnsupportedException`

ถูกยกเมื่อใด PdfWriter::build() ยกสิ่งนี้ที่จุดเข้า เมื่อ encryptionMode ของเอกสารเป็น pubkey (รายการ recipient แบบ public-key) ก่อนที่การ dispatch การเข้ารหัสลับ stream-body แบบ public-key ฝั่งตัวเขียนถูก เชื่อมต่อ การปฏิเสธตั้งแต่ต้นป้องกันการปล่อย PDF ที่ไม่เข้ารหัสลับซึ่ง ผู้เรียกเชื่อว่าถูกเข้ารหัสลับอย่างเงียบๆ
Carried data สืบทอดจาก RuntimeException โดยตรง มันจึงไม่ใช่ context-aware และไม่มี getContext() มันเป็นการ refine ที่เข้มงวดของ exception ทั่วไปที่ไซต์เดียวกันเคยยกขึ้น ตัวจัดการ catch (\RuntimeException) ที่มีอยู่จึงยังทำงานต่อไป
Recovery ใช้โหมดการเข้ารหัสลับที่รองรับ (การเข้ารหัสลับด้วยรหัสผ่าน) แทนรายการ recipient แบบ public-key หรือ pin ไปยังรีลีสที่มีการรองรับ การเข้ารหัสลับ public-key อย่าถือว่าเอาต์พุตถูกเข้ารหัสลับเมื่อสิ่งนี้ ถูกยก

อินพุตของ reader และ metadata

`UnsupportedPdfStructureException`

ถูกยกเมื่อใด ตัวอ่าน object-graph ยกสิ่งนี้ ล้มเหลวแบบปิด เมื่อ PDF input ตกอยู่นอก envelope ที่รองรับ ตัวอ่านรองรับ cross-reference table แบบดั้งเดิม (ISO 32000-2:2020 §7.5.4) cross-reference stream (§7.5.8) อ็อบเจ็กต์ที่บีบอัดแบบ object-stream (§7.5.7) ห่วงโซ่ /Prev แบบ multi-revision (§7.5.6) และไฟล์ hybrid-reference ผ่าน /XRefStm (§7.5.8.4) อะไรก็ตามนอก envelope นั้นจะปรากฏ exception นี้แทนการแยกวิเคราะห์ บางส่วนหรือแบบเดา constructor ที่ระบุชื่อ map ไปยังกรณีเหตุผล: encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile(), และ crossReferenceOffsetOutOfBounds()
Carried data สืบทอดจาก RuntimeException โดยตรง มันจึงไม่ใช่ context-aware และไม่มี getContext() มันเปิดเผยพร็อพเพอร์ตี public readonly reason ของชนิด UnsupportedPdfStructureReason (enum) เพื่อให้ผู้เรียก แยกกิ่งบนหมวดหมู่ที่แม่นยำโดยไม่แยกวิเคราะห์ข้อความ string detail ที่เป็น ทางเลือกและ throwable previous อาจเพิ่ม context ที่มีขอบเขตและไม่ละเอียดอ่อน ข้อความเริ่มต้นคือสรุปที่ไม่รั่วของเหตุผล
Recovery แยกกิ่งบน reason สำหรับ EncryptedDocument ให้รันขั้นตอน decrypt ก่อนอ่าน เพราะการถอดรหัสอยู่นอกขอบเขตของตัวอ่าน สำหรับ DamagedCrossReference, TruncatedFile, หรือ CrossReferenceOffsetOutOfBounds ให้ถือว่าไฟล์ผิดรูปหรือไม่ครบ และจัดหาใหม่หรือซ่อมแซมต้นทาง สำหรับ CyclicReferenceChain, NonConformantObjectStream, หรือ IrresolvableObjectCollision input ละเมิดโมเดลเชิงโครงสร้างและไม่อาจอ่านตามที่เป็นได้

`PacketTooLargeException`

ถูกยกเมื่อใด ตัวอ่านข้อมูลเมตา XMP แบบ streaming ยกสิ่งนี้เมื่อ แพ็กเก็ต XMP ที่ฝังเกินเพดานไบต์ที่กำหนดค่าไว้ มันเป็น guard ป้องกัน ต่อ input แบบ entity-expansion และ quadratic-blowup (เพดาน peak ที่ 128 MB ต่อ XMP ที่ฝังขนาดกิกะไบต์)
Carried data สืบทอดจาก NextPdfException แต่ไม่เขียนทับ getContext() ดังนั้น getContext() คืนอาร์เรย์ว่าง ข้อมูลวินิจฉัย อยู่บนพร็อพเพอร์ตี public readonly: byteCount (จำนวนไบต์ที่สังเกตได้) และ cap (cap ที่กำหนดค่าไว้เป็นไบต์) ข้อความรายงานทั้งสอง
Recovery ปฏิเสธหรือข้ามข้อมูลเมตาที่ใหญ่เกินว่าเป็นอันตรายหรือ ผิดรูป หากเอกสารที่ชอบธรรมจำเป็นต้องมีแพ็กเก็ตที่ใหญ่กว่าจริงๆ ให้เพิ่ม cap ที่กำหนดค่าไว้โดยเจตนา โดยชั่งความเสี่ยงการหมดหน่วยความจำที่ guard มีอยู่เพื่อป้องกัน

ดูเพิ่มเติม

Error reference index
Fonts and tagging troubleshooting — สำหรับอาการของ NotYetImplementedException, ScriptShaperException, และ IcuRequirementException
PDF/A and PDF/UA validation troubleshooting — สำหรับอาการของ Pdf14FeatureRejectedException และ Pdf20FeatureRejectedException
Encryption and permissions troubleshooting — สำหรับ PublicKeyEncryptionUnsupportedException และเหตุผล EncryptedDocument ของตัวอ่าน