核心與一般錯誤

適用範圍

下列條目涵蓋 NextPDF 所拋出的核心與通用例外狀況。大多數繼承自基底 NextPdfException，後者本身繼承 \RuntimeException 並實作 ContextAwareExceptionInterface。該介面揭露一個方法 getContext(): array，回傳一個由基本型別組成的扁平 snake_case 對應，可安全序列化到日誌或 APM 酬載。

以單一的 catch (NextPdfException $e) 攔截 NextPdfException 家族。另外加上一個 catch (\RuntimeException $e)，以涵蓋這組中少數直接繼承 \RuntimeException 的低階錯誤（列於下方）。基底 NextPdfException::getContext() 回傳空陣列；子類別會覆寫它以加入領域欄位。當某個類別未覆寫 getContext() 時，它沿用空陣列，而診斷細節改而存在於訊息與具型別的 getter 中。

這組中有四個型別不繼承 NextPdfException：BlackPointCompensationUnsupportedException 與 UnsupportedSourceDocumentException 直接繼承 \RuntimeException（請當作 \RuntimeException 攔截），而 ComplianceViolation 與 RuleViolation 是值物件、而非例外狀況——它們在此被記載，是因為它們建模了引擎所回傳的錯誤與違規資料。

基底例外狀況

NextPdfException

• 它是什麼。 NextPDF core 及其擴充套件所拋出每一個例外狀況的 abstract 基底。它繼承 \RuntimeException 並實作 ContextAwareExceptionInterface。攔截這單一型別即可截取任何函式庫錯誤。
• 脈絡。 基底 getContext() 回傳空陣列。子類別會覆寫它以回傳領域特定的欄位。
• 解法。 不會被直接拋出。把它當作兜底型別使用；對具體子類別分支以進行特定處理。

組態與功能開關

InvalidConfigException

• 何時被拋出。 當一個 Config 值或值的組合無效時——缺少必填設定、互斥的選項，或一個超出其可接受範圍的值。這代表開發者錯誤：呼叫端程式碼提供了一個必須在重試前更正的組態。訊息會回報鍵、預期的型別或範圍，以及所提供值的實際偵錯型別。
• 脈絡。 getContext() 回傳 config_key、given_value 與 expected_type。具型別的 getter：getConfigKey()、getGivenValue()、getExpectedType()。
• 解法。 開發者動作：在再次呼叫 NextPDF 之前，把具名的組態鍵修正為一個符合預期型別或範圍的值。

NotImplementedException

• 何時被拋出。 當一個公開 API 進入點被觸及，但其實作在當前版本中是刻意缺席的。用於已棄用的填補墊（shim），這些填補墊的存在是為了讓 pre-bisect 的呼叫端得到一個響亮、可採取行動的失敗，而非靜默的 no-op。訊息會結合一個可被機器 grep 的 feature 標籤與一個 followUp 參照（缺陷 ID、追蹤錨點或衝刺名稱）。
• 脈絡。 未覆寫 getContext()，因此它回傳空陣列。$feature 與 $followUp 值是公開的 readonly 屬性，並內嵌在訊息中。
• 解法。 函式庫呼叫端動作：移除該呼叫，或釘選到一個會帶來具名後續項目的未來版本。

IncompatibleFeatureFlagsException

• 何時被拋出。 在 Config 建置時（Config::validate()），當一個 CssFeatureFlags 組合內部不一致時——某個旗標預設了另一個被停用的旗標。今日唯一被禁止的組合是 layoutSubgrid = true 搭配 layoutGrid = false：一個 subgrid 化的軸從父格線容器衍生其格線線（CSS Grid Layout Module Level 2 §1），因此沒有 grid 的 subgrid 描述了一個不可能存在的格線。該檢查針對解析後的旗標執行，因此 CssRenderingMode::Safe（它強制每一個 Phase 4+ 功能關閉）會遮蔽該組合，而非觸發它。繼承 StrictModeViolation。
• 脈絡。 getContext() 把父嚴格模式欄位（cssDeviation、excId、chunkSha256、location）與 layoutGrid 及 layoutSubgrid 布林值合併。location 是 Config::validate()，而 cssDeviation 編碼了該旗標對。
• 解法。 函式庫呼叫端動作：在 layoutSubgrid 之外一併啟用 layoutGrid，或停用 layoutSubgrid。

IncompatibleRenderingModeException

• 何時被拋出。 在 Config 建置時，當一個 CssRenderingMode 與 CssLayoutMode 的配對落在模式矩陣的相容格之外時。今日唯一被禁止的配對是 CssRenderingMode::Safe + CssLayoutMode::Retained——Safe 強制每一個 Phase 4+ 功能關閉，使保留模式的格式化脈絡（Grid、Subgrid、@container）沒有消費者，因此該組合會被拒絕，而非被允許悄悄降級。繼承 StrictModeViolation。
• 脈絡。 getContext() 把父嚴格模式欄位與 mode1（繪製模式值）及 mode2（版面配置模式值）合併。cssDeviation 編碼了該模式對；location 是 Config::validate()。
• 解法。 函式庫呼叫端動作：為了回溯而選擇 Safe + Streaming，或為了 Grid/Subgrid/Container Queries 而選擇一個非 Safe 的繪製模式（Normal / Strict / Audit）搭配 Retained。

StrictModeViolation

• 何時被拋出。 在 CssRenderingMode::Strict 下所拋出任何規範偏離例外狀況的 abstract 基底。在嚴格模式中，任何未連結到已註冊 EXC-NNN 例外條目的已偵測 CSS 偏離，都會在偵測點拋出此類別（或子類別）的實例。不會被直接拋出；請參見 IncompatibleFeatureFlagsException 與 IncompatibleRenderingModeException。
• 脈絡。 getContext() 回傳四個 ADR-023 欄位：cssDeviation（偏離構造的簡短標籤）、excId（已註冊時的登錄識別碼，否則為 null）、chunkSha256（已知時的規範引用區塊雜湊，否則為 null），以及 location（呼叫端可讀的來源，否則為 null）。
• 解法。 函式庫呼叫端動作：把該偏離註冊為一個新的、已簽核的 EXC-NNN 條目，或修正繪製器以移除該偏離。

HTML 與 CSS 輸入

HtmlParsingException

• 何時被拋出。 當 HTML 輸入解析或 DOM 建構失敗時：無效的字元集宣告、輸入大小限制違反、過度的巢狀深度、元素計數溢位，以及表格結構錯誤（例如列數上限）。CSS 特定的資源耗盡改由 CssParserLimitExceededException 與 CssResolutionBudgetExceededException 回報。
• 脈絡。 getContext() 回傳 html_snippet（出問題 HTML 的簡短、被截斷的摘錄）、position（位元組偏移，未知時為 -1）與 rule（被違反的解析器限制）。具型別的 getter：getHtmlSnippet()、getPosition()、getRule()。
• 解法。 開發者動作：簡化 HTML 輸入，或調整解析器限制。

CssParserLimitExceededException

• 何時被拋出。 當 CSS 輸入超出所設定的解析器安全限制時。透過具名建構式涵蓋兩種類別：forByteLimit()（樣式表過大，無法安全進行 regex 處理）與 forNestingDepth()（CSS 巢狀遞迴過深）。兩則訊息都會具名說明實際值與限制。
• 脈絡。 getContext() 回傳 limit_type（byte 或 nesting_depth）、actual 與 limit。
• 解法。 開發者動作：把樣式表拆分成較小的工作表、縮減巢狀深度，或提高所設定的限制。

CssResolutionBudgetExceededException

• 何時被拋出。 當 CSS :has() 解析超出其遍歷預算時。雙遍 :has() 解析器強制執行一個嚴格的節點走訪預算，以防止病態的選擇器造成二次方的文件走訪；一旦總走訪次數超出限制，該樣式表就會因過於複雜而被拒絕。訊息會具名說明走訪次數與預算。
• 脈絡。 getContext() 回傳 visits 與 budget。具型別的 getter：getVisits()、getBudget()。
• 解法。 開發者動作：降低選擇器複雜度，或提高所設定的預算。

字型與影像

FontNotFoundException

• 何時被拋出。 當在檔案系統層級無法定位或讀取字型檔時：所請求的字族或路徑不存在、無法讀取，或所設定的字型目錄無法存取。字型資料本身可能有效——這只代表它無法被觸及。訊息會列出搜尋過的路徑。
• 脈絡。 getContext() 回傳 font_name、search_paths（一個清單）與 fallback_attempted（一個 bool）。具型別的 getter：getFontName()、getSearchPaths()、wasFallbackAttempted()。
• 解法。 開發者動作：查驗字型路徑。基礎設施動作：修正字型檔或目錄上的檔案權限。

FontParsingException

• 何時被拋出。 當找到字型檔、但其內容不可用時：它已損毀、格式不受支援，或缺少必要的表。涵蓋 TrueType、Type 1、CFF 與 OpenType 解析期間的結構驗證失敗——被截斷的標頭、無效的表目錄、缺少必填表（head、hhea、OS/2）、解包錯誤與大小違反。訊息會具名說明檔案與解析錯誤。
• 脈絡。 getContext() 回傳 font_file 與 parse_error。具型別的 getter：getFontFile()、getParseError()。
• 解法。 開發者動作：以一個有效的字型檔取代該檔案。

ImageProcessingException

• 何時被拋出。 當影像無法被解碼、格式不受支援，或 GD/Imagick 處理失敗時：無法辨識的魔術位元組、損毀的 JPEG 資料、不受支援的 MIME 型別、檔案大小限制違反，以及 GD 資源配置失敗。影像可存取，但其像素資料無法被擷取以供內嵌。
• 脈絡。 getContext() 回傳 image_path（內嵌資料時為空）、format（偵測到或預期的，例如 jpeg、png、unknown）與 operation（例如 decode、resize、embed）。具型別的 getter：getImagePath()、getFormat()、getOperation()。
• 解法。 開發者動作：提供一個有效、受支援的影像檔。

輸出、版面配置與序列化

CompressionException

• 何時被拋出。 當 FlateDecode（zlib）壓縮或解壓縮失敗時——在內容串流、字型資料、頁面內容、附件資料與交互參照串流上的 gzcompress/gzuncompress 失敗。通常是損毀的輸入串流、記憶體不足，或缺少 zlib 擴充功能。
• 脈絡。 getContext() 回傳 algorithm（過濾器名稱，例如 FlateDecode、LZWDecode）與 stream_length（位元組長度，未知時為 -1）。具型別的 getter：getAlgorithm()、getStreamLength()。
• 解法。 基礎設施動作：查驗 ext-zlib 已載入且記憶體充足。

WriterException

• 何時被拋出。 當 PDF 序列化、線性化或 I/O 輸出失敗時：PdfWriter 串流寫入錯誤、交互參照表損毀、標頭/trailer 產生失敗、物件參照解析失敗、檔案寫入錯誤，以及輸出緩衝區溢位。一份有效的記憶體內文件無法被序列化為一個有效的位元組串流。訊息會具名說明階段。
• 脈絡。 getContext() 回傳 output_path（字串輸出時為空）與 writer_state（階段，例如 header、body、xref、trailer）。具型別的 getter：getOutputPath()、getWriterState()。
• 解法。 基礎設施動作：檢查磁碟空間、檔案權限與輸出串流。

PageLayoutException

• 何時被拋出。 當頁面版面配置限制無法被滿足時：欄版面配置違反（寬度不足、無效的欄數）、內容溢出頁面邊界，以及邊界衝突。對於給定的頁面尺寸與內容，所請求的版面配置在幾何上是不可能的。訊息會在已知時具名說明頁碼與被違反的限制。
• 脈絡。 getContext() 回傳 page_number（從 1 起算，未知時為 0）與 constraint。具型別的 getter：getPageNumber()、getConstraint()。
• 解法。 開發者動作：調整頁面尺寸、邊界、欄設定或內容。

TemplateException

• 何時被拋出。 當 TemplateManager 中的 PDF 範本匯入或重用操作失敗時：無效的範本狀態轉移（範本的開始或結束順序錯誤）、參照一個不存在的範本，以及範本序列化期間的串流壓縮失敗。訊息會具名說明操作，以及範本 id 已被指派時的範本 id。
• 脈絡。 getContext() 回傳 template_id（尚未指派時為空）與 operation（例如 begin、end、use、serialize）。具型別的 getter：getTemplateId()、getOperation()。
• 解法。 開發者動作：修正範本使用順序或來源 PDF。

內容串流不變量

ContentStreamBalanceException

• 何時被拋出。 當 ContentStreamBuilder 在串流關閉時（或在不變量被即時斷言時於串流中途）偵測到一個不平衡的運算子對時。它擷取未通過平衡不變量的深度計數器，使記錄能辨識是哪個發送器洩漏了一個沒有對應 Q、ET 或 EMC 的 q、BT 或 BMC。依 ISO 32000-2:2020 §8.4.2（圖形狀態堆疊）、§9.4.1（文字物件）與 §14.6（標記內容）。
• 脈絡。 getContext() 回傳 graphics_depth、text_block_depth、marked_content_depth 與 offending_operator。具型別的 getter：getGraphicsDepth()、getTextBlockDepth()、getMarkedContentDepth()、getOffendingOperator()。
• 解法。 開發者動作：定位那個開啟了某個構造卻未將其關閉的發送器。

GraphicsStateBalanceException

• 何時被拋出。 當一個 PDF 內容串流以不平衡的 q/Q 運算子關閉時。ISO 32000-2:2020 §8.4.2 要求每一個圖形狀態儲存（q）在串流結束前都恰好對應一個還原（Q）；不平衡會把變換、裁切路徑、色彩與繪製意圖洩漏到後續頁面或 Form XObject。僅在嚴格圖形狀態檢查啟用時（NEXTPDF_GFXSTATE_STRICT=1）才會引發；在寬鬆模式中，改為透過 trigger_error() 發出一則警告。
• 脈絡。 getContext() 回傳 save_depth（儲存過多時為正，還原過多時為負）。具型別的 getter：getSaveDepth()。
• 解法。 開發者動作：定位未配對的 save()/restore() 對。

MissingShadingResourceException

• 何時被拋出。 當 ConicGradientRenderer::render() 在沒有 Shading 資源登錄脈絡的情況下被呼叫時。v10.0.0 的破壞性變更移除了先前隱含標記對應的代理路徑：呼叫端必須以一個 ShadingResourceRegistryInterface 建構繪製器，使 /ShadingType 4 間接物件得以對該頁面的 Shading 資源子字典註冊（ISO 32000-2 §8.7.4.2 / §8.7.4.3）。訊息會具名說明呼叫端脈絡，並指向 v9.x→v10.0 的遷移註記。
• 脈絡。 getContext() 回傳 context（一個簡短的呼叫端脈絡標籤，例如 ConicGradientRenderer::render）。
• 解法。 函式庫呼叫端動作：在呼叫 render() 之前，把一個 Shading 資源登錄實例接線到繪製器建構式中。

線性化（Fast Web View）

LinearizationInvariantException

• 何時被拋出。 當 v2 三遍 Linearizer 偵測到其 MEASURE → PLACE → FILL 斷言遭違反時：Pass 3 的位元組計數與 Pass 1 預測的檔案長度不符（偏移漂移）、線性化字典佔位符對於序列化後的寬度而言過小，或一個 /H [offset length] 提示串流偏移與最終輸出不符。揭露這一點、而非發出一份壞掉的 PDF，是一項已載明的安全保證。
• 脈絡。 getContext() 回傳 invariant（被違反的不變量名稱）、expected、actual 與 delta（帶正負號的差值）。具型別的 getter：getInvariant()、getExpectedValue()、getActualValue()。
• 解法。 維護者動作：提交一份缺陷回報——這些不變量對所有格式良好的輸入都應成立。擷取鏈結的前一個例外狀況。

LinearizationUnimplementedException

• 何時被拋出。 當線性化器功能旗標被設為一個刻意停用的後端時。目前僅對 linearizerVersion === 'v1-noop' 引發，這是緊急降級設定，可在執行階段拒絕所有線性化嘗試，無須變更程式碼或重新部署——適用於在生產中緊急關閉 Fast Web View。
• 脈絡。 getContext() 回傳 reason（一個簡短、人類可讀的說明）。具型別的 getter：getReason()。
• 解法。 維運/發行工程動作：調整組態，或升級到一個已修正的後端版本。

規範與設定檔不變量

ConformanceViolationException

• 何時被拋出。 當一個被請求的功能無法在不破壞文件所宣告之 ISO 規範合約的情況下發出，而引擎寧可失敗即關閉、也不寫出一個不符規範的物件時。標準觸發是在 PDF/A 封存設定檔下的一個多媒體 Screen 註解或 Rendition 動作（ISO 32000-2:2020 §12.5.6.18 / §13.2），這是每個 PDF/A 部分都禁止的（ISO 19005 系列）——該檔案會無法通過 veraPDF 驗證，因此引擎事先就拒絕。
• 脈絡。 getContext() 回傳 conformance_mode（所宣告的模式，例如 pdfa4）與 feature（被拒絕的功能，例如 Screen annotation）。兩者都是公開的 readonly 屬性。原因即例外狀況訊息。
• 解法。 開發者動作：為封存輸出捨棄該多媒體呼叫，或以一個非封存的規範設定檔為目標（預設為 ConformanceMode::Plain）。

PdfRViolationException

• 何時被拋出。 當一個 PDF/R-1（ISO 23504-1:2020）規範不變量遭違反時，無論是在值物件建構時（PdfRStrip、PdfRPage、PdfRDocument 設定檔），或在驗證器時（PdfRValidator）。它擷取出問題的規範子句與一行違規描述，使稽核消費者無須解析自由文字就能把發現路由到正確的 §6 子句。
• 脈絡。 getContext() 回傳 standard（一律為 ISO 23504-1:2020）、clause（子句路徑，例如 6.6.1）與 violation。具型別的 getter：getClause()、getViolation()。
• 解法。 開發者動作：更正被拒絕的輸入，或重建文件使其符合所引用的子句。

條碼產生

BarcodeException

• 何時被拋出。 當條碼產生因無效資料或編碼錯誤而失敗時，橫跨所有受支援的符號體系（Code 39/128、UPC-A/E、EAN-8/13、Interleaved/Standard 2-of-5、POSTNET、PLANET、MSI、ISBN、ISSN、QR Code、PDF417、DataMatrix、JabCode），以及影像建立期間的 GD 繪製失敗。條碼值在訊息與脈絡中被摘錄上限至 128 個位元組——過長或二進位的酬載會以一個 ... (<N> bytes, truncated) 標記被截斷儲存，使其無法被整個複製到日誌中。
• 脈絡。 getContext() 回傳 barcode_type（符號體系，例如 QRCODE、EAN13、CODE128）與 value（被截斷的值）。具型別的 getter：getBarcodeType()、getValue()。
• 解法。 開發者動作：更正條碼資料或符號體系選擇。

BarcodeEncoderNotFoundException

• 何時被拋出。 當所請求的編碼器型別未知，或其能力開關關閉時，從 BarcodeEncoderRegistry 拋出。它也實作 PSR-11 Psr\Container\NotFoundExceptionInterface，因此該登錄是一個符合標準的容器。訊息會具名說明符號體系與原因。
• 脈絡。 未覆寫 getContext()，因此它回傳空陣列。type 與 reason 可透過 getType() 與 getReason() getter 以及在訊息中取得。
• 解法。 開發者動作：註冊該編碼器，或安裝提供它的套件（例如 nextpdf/pro 提供 Micro QR / DotCode / HanXin / JabCode）。

密碼學、加密與簽章

EncryptionException

• 何時被拋出。 當 PDF 加密或解密失敗時：AES-256-CBC 加密/解密失敗、OpenSSL 錯誤、無效的 IV 大小、雜湊計算失敗，以及 UE/OE 值計算錯誤。通常是缺少或設定錯誤的 OpenSSL 擴充功能、無效的金鑰材料，或損毀的加密資料。訊息會具名說明操作與演算法。
• 脈絡。 getContext() 回傳 algorithm（例如 AES-256-CBC）與 operation（例如 encrypt、decrypt、key_derivation）。具型別的 getter：getAlgorithm()、getOperation()。
• 解法。 基礎設施動作：確保 OpenSSL 可用且正確設定。請參見加密與權限。

UnsupportedAlgorithmException

• 何時被拋出。 當一個密碼學演算法在當前執行階段無法被執行時：所需的 PHP 擴充功能不可用、底層函式庫缺少該基元、隨附的 hash 擴充功能無法合成一個 SHAKE/XOF 變體，或該演算法未在 SignatureAlgorithmRegistry 中註冊。引擎不得悄悄降級到一個較弱的基元，因此它改而揭露這個。靜態工廠 nonFipsHostUnderFipsProfile() 會在選定了 RegulatoryProfile::FIPS、但無法確認一個經 FIPS 驗證的 OpenSSL 提供者時引發它（FIPS_ABSENT 與 INDETERMINATE 兩者都失敗即關閉），並帶有演算法識別碼 regulatory-profile:fips。
• 脈絡。 getContext() 回傳 algorithm（名稱或 OID，例如 shake256、Ed25519、AES-256-GCM）與 reason（維運人員可採取行動）。具型別的 getter：getAlgorithm()、getReason()。
• 解法。 維運人員動作：安裝缺少的擴充功能或升級執行階段；對於 FIPS 閘門，安裝一個經 FIPS 驗證的 OpenSSL 建置，或明確設定 NEXTPDF_FIPS_MODE。開發者動作：透過 SignatureAlgorithmRegistry::register() 註冊一個自訂演算法描述子。

SignatureException

• 何時被拋出。 當一個數位簽章操作失敗時：憑證與私密金鑰處理（PKCS#12 解析、PEM/DER 解碼、X.509 驗證）、PKCS#7/CMS 建構、ECDSA 簽章格式、容器大小違反、DER 編碼，以及 PAdES 協調。TSA 特定的錯誤改由更具體的 TsaException 回報。請偏好具型別的具名工廠，而非位置式建構式；每一個都會把根本原因綁定到訊息尾端。範例：ltvCapabilityMissing()（B-LT/B-LTA 需要 nextpdf/enterprise）、tsaRequired() / tsaUrlEmpty() / tsaEmptyToken()、httpClientMissing()、hsmSignerMissing() / hsmSignatureEmpty()、signatureContentsNotFound() / signatureContentsPaddingCorrupt()、unexpectedKeyType()、pemDecodingFailed()、Ed25519 家族（ed25519SignatureMalformed()、ed25519RoundTripVerifyFailed()、ed25519KeyParseFailed()、ed25519SeedInvalid()、ed25519SecretKeyMalformed()、ed25519PublicKeyInvalid()）、documentTimestampNotEmitted()、algorithmPolicyRejected()、digestOnlyAlgorithmRefused()、encryptedLtvUnsupported()、incrementalUpdateWriterMissing()，以及 OCSP 狀態對 nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus()（RFC 6960 §4.2.1）。這些工廠寧可失敗即關閉，也不發出一份悄悄被降階的簽章。
• 脈絡。 getContext() 回傳 cert_info（主體 DN 或指紋，或為空）、signature_level（所嘗試的 PAdES 層級，例如 B-B、B-T、B-LT、B-LTA）與 detail（可採取行動的診斷，舊式位置式建構式時為空）。具型別的 getter：getCertInfo()、getSignatureLevel()、getDetail()。
• 解法。 開發者動作：修正憑證/金鑰組態。對於能力缺漏的工廠，安裝具名的套件。請參見簽章與時間戳記失敗，以取得各工廠的症狀與解法條目。

BlackPointCompensationUnsupportedException

• 何時被拋出。 當呼叫端要求 null 轉接器套用一個非 Default 的 ISO 18619 黑點補償變換時，從 NullBlackPointCompensationTransform::transform() 拋出。null 轉接器是沒有色彩管理後端的環境的安全退路；在沒有真正的色彩管理模組下產生一個變換後的取樣，會悄悄誤報該轉換。與此處大多數條目不同，它直接繼承 \RuntimeException、而非 NextPdfException，因此既有的 catch (\RuntimeException) 路徑仍可運作。
• 脈絡。 無 getContext()；它是一個純粹的 \RuntimeException。細節在訊息中。
• 解法。 開發者動作：註冊一個真正的 BlackPointCompensationTransform（LittleCMS、Argyll、純 PHP），或把 /UseBlackPtComp 限制為 BlackPointCompensation::Default。

文件組裝與無障礙

UnsupportedSourceDocumentException

• 何時被拋出。 當一份來源文件無法被安全地複製到合併/分割輸出中，而該操作寧可失敗即關閉、也不發出一個損毀或安全受損的結果時。請使用具名工廠：encrypted()（ISO 32000-2 §7.6——沒有金鑰就無法複製內容）、signed()（§12.8——複製頁面會使簽章的位元組範圍失效）、unsupportedStreamFilter()（物件圖讀取器無法來回轉換的過濾器）、multipleInteractiveForms()（一項已載明的限制：超過一個來源攜帶非空的 /AcroForm，§12.7），以及 splitWithInteractiveForm()（一項已載明的限制：對一個攜帶表單的來源進行頁面子集化會使 widget 成為孤兒）。直接繼承 \RuntimeException、而非 NextPdfException。
• 脈絡。 無 getContext()；它是一個純粹的 \RuntimeException。成因與受影響的物件號碼會具名於訊息中。
• 解法。 開發者動作：先解密來源或提供金鑰；對於已簽署的來源，改在合併後再簽署；對於多表單合併，將除一個來源以外的所有表單欄位平面化或移除；對於攜帶表單的分割，在分割前將表單平面化。

InvalidBcp47TagException

• 何時被拋出。 當一個候選語言標籤在 RFC 5646 §2.1 ABNF 下格式錯誤，或未通過策劃的登錄查找時，從 Bcp47Validator::validate() 拋出。它對 BCP-47 / ISO 14289-2:2024 §8.4.4 是領域特定的，與 InvalidConfigException 不同，使無障礙接縫下游的呼叫端能攔截一個狹義的型別。述詞對 Bcp47Validator::isWellFormed() / isValid() 仍是供偏好分支而非例外狀況的呼叫端使用的、向後相容的回傳值介面。
• 脈絡。 getContext() 回傳 tag（與所提供完全相同的候選）與 reason（一個穩定、機器可讀的拒絕代碼，例如 empty-string、well-formed-shape、unregistered-primary、duplicate-variant）。具型別的 getter：getTag()、getReason()。
• 解法。 開發者動作：把語言標籤更正為一個格式良好、已註冊的 BCP-47 標籤。請參見字型與標記。

FormFieldAccessibilityException

• 何時被拋出。 當一個互動式表單欄位會在啟用嚴格無障礙欄位名稱強制下產生一份 PDF/UA 文件時、仍仰賴一個合成（非作者提供）的無障礙名稱時。預設的 PDF/UA 輸出會把一個合成的退路名稱發送到 widget 的 /Contents，使欄位永不會無名；嚴格模式則要求作者提供一個有意義的名稱（一個工具提示，或一個無動作下推按鈕的標題），使螢幕閱讀器使用者能得到一個真實的描述（ISO 14289-2:2024 §8.10.2）。
• 脈絡。 未覆寫 getContext()，因此它回傳空陣列。$fieldId 是一個公開的 readonly 屬性；原因即訊息。
• 解法。 開發者動作：在產生一份嚴格的 PDF/UA 文件之前，為具名的欄位提供一個工具提示/無障礙名稱，或停用嚴格模式。請參見 PDF/A 與 PDF/UA 驗證。

VendorExtensionRegistryConflictException

• 何時被拋出。 當呼叫端以一個與已註冊中介資料相牴觸的描述，重新註冊一個已知的 PDF 開發者擴充功能廠商前綴（ISO 32000-2:2020 §7.12.1）時，從 VendorExtensionRegistry::register() 拋出。描述子是僅可附加且具衝突偵測的；此具型別的例外狀況取代了通用的 \RuntimeException，使呼叫端能攔截這個特定類別。
• 脈絡。 getContext() 回傳 prefix、existing_description 與 attempted_description。具型別的 getter：getPrefix()、getExistingDescription()、getAttemptedDescription()。
• 解法。 開發者動作：以既有的描述註冊該前綴，或使用一個不同的前綴；不要覆寫已註冊的中介資料。

稽核匯出

AuditExportException

• 何時被拋出。 當稽核匯出組合包組裝、可追溯性矩陣產生，或結構描述投影在執行階段失敗時。涵蓋對 claims.json / manifest.json 的 I/O、標準組合包的 JSON 編碼/解碼，以及 AuditExporter::projectToV1() 向後相容路徑上的結構描述版本不符。訊息會具名說明階段、已知時的產物，以及細節。
• 脈絡。 getContext() 回傳 stage（例如 read_claims、encode_bundle、project_v1）、detail 與 artefact（觸發失敗的路徑或 schema_version）。具型別的 getter：getStage()、getDetail()、getArtefact()。
• 解法。 合規/DevOps 動作：查驗輸入產物路徑、從一次乾淨的執行重新產生 claims.json，或在重新嘗試匯出前重建 manifest。

違規值物件

這些不是例外狀況。它們是引擎所回傳、用以描述個別違規的不可變值物件；它們不攜帶 getContext()。

ComplianceViolation

• 它是什麼。 一個 final readonly 值物件，代表由外部驗證器（veraPDF 或同等者）所回報的一項規則失敗，包含 ISO 子句參照與其在 PDF 結構內的位置。
• 欄位。 公開的 readonly 屬性：ruleId（驗證器規則識別碼，例如 6.1.2-1）、clause（ISO 子句參照，例如 ISO 19005-1:2005, 6.1.2）、severity（例如 error、warning）、location（PDF 結構內的物件路徑）與 message（人類可讀的描述）。
• 用途。 檢視一個合規驗證器所回傳的集合；依 severity 與 clause 路由或顯示每個條目。請參見 PDF/A 與 PDF/UA 驗證。

RuleViolation

• 它是什麼。 一個 final readonly 值物件，代表一項 Schematron / EN 16931 商業規則違規，由 SchematronRunnerInterface::runRules() 回傳並彙整於 ValidationResult::$ruleViolations 之內。穩定性為 experimental。
• 欄位。 公開的 readonly 屬性：ruleId（EN 16931 識別碼，例如 BR-{n}、BR-CO-{n}、BR-CL-{n}、BR-DEC-{n}，或某個層級特定的套件）、severity（一個 RuleSeverity 列舉）、message（規則文字，en-GB）、xpath（指向內嵌 XML 的 XPath，文件範圍規則時為 null），以及 semanticPath（點記法的 BG/BT 路徑，例如 BG-22.BT-106，結構性違規時為 null）。
• 用途。 檢視驗證結果上的集合；依 severity、ruleId 與定位器路由或顯示每個條目。

另請參閱

• 錯誤參考索引
• 知識庫索引
• 簽章與時間戳記失敗
• 加密與權限
• 字型與標記
• PDF/A 與 PDF/UA 驗證