核心与通用错误

范围

这些条目涵盖 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

• What it is. 它是 NextPDF 核心及其扩展包抛出的每个异常的 abstract 基类。它继承 \RuntimeException 并实现 ContextAwareExceptionInterface。捕获这一个类型即可拦截任何库错误。
• Context. 基类 getContext() 返回一个空数组。子类会重写它以返回特定领域的字段。
• Recovery. 不会被直接抛出。把它当作万能捕获类型来用； 按具体子类分支以进行特定处理。

配置与功能门控

InvalidConfigException

• When it is thrown. 当某个 Config 值或多个值的组合无效时——缺少必填设置、互斥选项，或某个值超出其可接受范围。这表示一个开发者错误：调用方代码提供了一份必须先纠正才能重试的配置。消息会报告该键、期望的类型或范围，以及所提供值的实际调试类型。
• Context. getContext() 返回 config_key、given_value 和 expected_type。类型化 getter：getConfigKey()、getGivenValue()、 getExpectedType()。
• Recovery. 开发者操作：在再次调用 NextPDF 之前，把指定的配置键修正为期望类型或范围内的值。

NotImplementedException

• When it is thrown. 当到达某个公开 API 入口点，但其实现在当前版本中被有意省略时。用于已弃用的垫片，它们的存在是为了给 pre-bisect 调用方一个响亮、可操作的失败，而非一个静默的空操作。消息会组合一个可被机器 grep 的 feature 标签和一个 followUp 引用（缺陷 ID、跟踪锚点或迭代名称）。
• Context. 不重写 getContext()，因此它返回一个空数组。 $feature 和 $followUp 值是公开的 readonly 属性，并嵌入在消息中。
• Recovery. 库调用方操作：移除该调用，或固定到一个将落地所指名 follow-up 的未来版本。

IncompatibleFeatureFlagsException

• When it is thrown. 在 Config 构建时（Config::validate()），当一个 CssFeatureFlags 组合在内部自相矛盾时——某个标志以另一个被禁用的标志为前提。今天唯一被禁止的组合是 layoutSubgrid = true 与 layoutGrid = false：一个 subgrid 轴从父级网格容器派生出它的网格线（CSS Grid Layout Module Level 2 §1），因此没有 grid 的 subgrid 描述的是一个不可能存在的网格。该检查针对已解析的标志运行，因此 CssRenderingMode::Safe（它会强制关闭每个 Phase 4+ 特性）会掩盖该组合，而非触发它。继承自 StrictModeViolation。
• Context. getContext() 会把父级严格模式字段 （cssDeviation、excId、chunkSha256、location）与 layoutGrid 和 layoutSubgrid 布尔值合并。location 为 Config::validate()， cssDeviation 则编码了这对标志。
• Recovery. 库调用方操作：在启用 layoutSubgrid 的同时启用 layoutGrid，或禁用 layoutSubgrid。

IncompatibleRenderingModeException

• When it is thrown. 在 Config 构建时，当一对 CssRenderingMode 与 CssLayoutMode 的搭配落在模式矩阵的兼容单元格之外时。 今天唯一被禁止的搭配是 CssRenderingMode::Safe + CssLayoutMode::Retained——Safe 会强制关闭每个 Phase 4+ 特性，使得 retained 模式的格式化上下文（Grid、Subgrid、@container）没有消费方，因此该组合会被拒绝，而非被允许静默降级。继承自 StrictModeViolation。
• Context. getContext() 会把父级严格模式字段与 mode1 （渲染模式值）和 mode2（布局模式值）合并。 cssDeviation 编码了这对模式；location 为 Config::validate()。
• Recovery. 库调用方操作：选择 Safe + Streaming 进行回滚， 或选择一个非 Safe 的渲染模式（Normal / Strict / Audit）搭配 Retained 以使用 Grid / Subgrid / Container Queries。

StrictModeViolation

• When it is thrown. 它是在 CssRenderingMode::Strict 下抛出的任何规范偏离异常的 abstract 基类。在严格模式下，任何检测到的、 未与已注册的 EXC-NNN 异常条目关联的 CSS 偏离，都会在检测点抛出该类（或其子类）的一个实例。不会被直接抛出；参见 IncompatibleFeatureFlagsException 与 IncompatibleRenderingModeException。
• Context. getContext() 返回 ADR-023 的四个字段：cssDeviation （偏离构造的简短标签）、excId（已注册时为注册表标识符，否则为 null）、chunkSha256（已知时为规范引用的 chunk 哈希， 否则为 null），以及 location（调用方可读的来源，否则为 null）。
• Recovery. 库调用方操作：把该偏离注册为一个新的、 经签核的 EXC-NNN 条目，或修复渲染器以消除该偏离。

HTML 与 CSS 输入

HtmlParsingException

• When it is thrown. 当 HTML 输入解析或 DOM 构建失败时： 无效的字符集声明、输入大小限制违规、过深的嵌套深度、元素数量溢出，以及诸如行数上限之类的表格结构错误。CSS 特有的资源耗尽则改由 CssParserLimitExceededException 和 CssResolutionBudgetExceededException 报告。
• Context. getContext() 返回 html_snippet（出问题 HTML 的一段简短、 截断的摘录）、position（字节偏移量，若未知则为 -1），以及 rule（被违反的解析器约束）。类型化 getter：getHtmlSnippet()、 getPosition()、getRule()。
• Recovery. 开发者操作：简化 HTML 输入或调整解析器限制。

CssParserLimitExceededException

• When it is thrown. 当 CSS 输入超出某个已配置的解析器安全限制时。通过具名构造函数覆盖两个类别： forByteLimit()（样式表过大，无法安全地进行正则处理）和 forNestingDepth()（CSS 嵌套递归过深）。两条消息都会指明实际值与限制值。
• Context. getContext() 返回 limit_type（byte 或 nesting_depth）、 actual 和 limit。
• Recovery. 开发者操作：把样式表拆分为更小的表，或降低嵌套深度，或提高已配置的限制。

CssResolutionBudgetExceededException

• When it is thrown. 当 CSS :has() 解析超出其遍历预算时。两遍式 :has() 解析器会强制执行一个严格的节点访问预算， 以防止病态选择器导致文档的二次遍历；一旦累计访问次数超过限制，该样式表就会因过于复杂而被拒绝。消息会指明访问次数与预算。
• Context. getContext() 返回 visits 和 budget。类型化 getter： getVisits()、getBudget()。
• Recovery. 开发者操作：降低选择器复杂度，或提高已配置的预算。

字体与图像

FontNotFoundException

• When it is thrown. 当在文件系统层面无法定位或读取某个字体文件时：所请求的字族或路径不存在、不可读取，或已配置的字体目录不可访问。字体数据本身可能是有效的——这只表示它无法被触及。消息会列出所搜索的路径。
• Context. getContext() 返回 font_name、search_paths（一个列表）和 fallback_attempted（一个布尔值）。类型化 getter：getFontName()、 getSearchPaths()、wasFallbackAttempted()。
• Recovery. 开发者操作：核实字体路径。基础设施操作： 修复字体文件或目录的文件权限。

FontParsingException

• When it is thrown. 当找到了字体文件但其内容不可用时：它已损坏、采用不受支持的格式，或缺少必需的表。 涵盖 TrueType、Type 1、CFF 与 OpenType 解析期间的结构验证失败——截断的头部、无效的表目录、缺少强制表（head、hhea、OS/2）、解包错误，以及大小违规。消息会指明文件和解析错误。
• Context. getContext() 返回 font_file 和 parse_error。类型化 getter：getFontFile()、getParseError()。
• Recovery. 开发者操作：用一个有效的字体文件替换它。

ImageProcessingException

• When it is thrown. 当某个图像无法被解码、采用不受支持的格式，或未能通过 GD/Imagick 处理时：无法识别的魔术字节、损坏的 JPEG 数据、不受支持的 MIME 类型、文件大小限制违规，以及 GD 资源分配失败。该图像本身可访问，但其像素数据无法被提取以供嵌入。
• Context. getContext() 返回 image_path（内联数据时为空）、 format（检测到的或期望的，例如 jpeg、png、unknown），以及 operation（例如 decode、resize、embed）。类型化 getter： getImagePath()、getFormat()、getOperation()。
• Recovery. 开发者操作：提供一个有效、受支持的图像文件。

输出、布局与序列化

CompressionException

• When it is thrown. 当 FlateDecode（zlib）压缩或解压失败时——在内容流、字体数据、页面内容、附件数据和交叉引用流上的 gzcompress/gzuncompress 失败。通常是某个损坏的输入流、内存不足，或缺少 zlib 扩展。
• Context. getContext() 返回 algorithm（过滤器名称，例如 FlateDecode、LZWDecode）和 stream_length（字节长度，若未知则为 -1）。 类型化 getter：getAlgorithm()、getStreamLength()。
• Recovery. 基础设施操作：核实 ext-zlib 已加载且内存充足。

WriterException

• When it is thrown. 当 PDF 序列化、线性化或 I/O 输出失败时：PdfWriter 流写入错误、交叉引用表损坏、 头部/尾部生成失败、对象引用解析失败、文件写入错误，以及输出缓冲区溢出。一个有效的内存中文档未能被序列化为有效的字节流。消息会指明所处阶段。
• Context. getContext() 返回 output_path（字符串输出时为空） 和 writer_state（所处阶段，例如 header、body、xref、trailer）。 类型化 getter：getOutputPath()、getWriterState()。
• Recovery. 基础设施操作：检查磁盘空间、文件权限，以及输出流。

PageLayoutException

• When it is thrown. 当页面布局约束无法被满足时： 分栏布局违规（宽度不足、列数无效）、内容溢出页面边界，以及边距冲突。所请求的布局对于给定的页面尺寸和内容而言在几何上是不可能的。 消息会在已知时指明页码，以及被违反的约束。
• Context. getContext() 返回 page_number（从 1 起算，若未知则为 0）和 constraint。类型化 getter：getPageNumber()、 getConstraint()。
• Recovery. 开发者操作：调整页面尺寸、边距、分栏设置或内容。

TemplateException

• When it is thrown. 当 TemplateManager 中的某个 PDF 模板导入或重用操作失败时：无效的模板状态转换（不按顺序地开始或结束模板）、引用一个不存在的模板，以及模板序列化期间的流压缩失败。消息会指明该操作，以及已分配时的模板 id。
• Context. getContext() 返回 template_id（尚未分配时为空） 和 operation（例如 begin、end、use、serialize）。类型化 getter： getTemplateId()、getOperation()。
• Recovery. 开发者操作：修正模板的使用顺序或源 PDF。

内容流不变量

ContentStreamBalanceException

• When it is thrown. 当 ContentStreamBuilder 在流关闭时（或在急切断言不变量时于流中途）检测到一对不平衡的操作符时。它会捕获未能通过平衡不变量的深度计数器，以便日志可以识别出是哪个写出器泄漏了一个没有对应 Q、ET 或 EMC 的 q、BT 或 BMC。依据 ISO 32000-2:2020 §8.4.2（图形状态栈）、§9.4.1（文本对象）和 §14.6（标记内容）。
• Context. getContext() 返回 graphics_depth、text_block_depth、 marked_content_depth 和 offending_operator。类型化 getter： getGraphicsDepth()、getTextBlockDepth()、getMarkedContentDepth()、 getOffendingOperator()。
• Recovery. 开发者操作：定位那个打开了某个构造却未将其关闭的写出器。

GraphicsStateBalanceException

• When it is thrown. 当一个 PDF 内容流以不平衡的 q/Q 操作符关闭时。ISO 32000-2:2020 §8.4.2 要求每个图形状态保存（q） 在流结束前都恰好被一个恢复（Q）匹配；不平衡会把变换、裁剪路径、颜色和渲染意图泄漏到后续页面或 Form XObject 中。仅当启用严格图形状态检查时才抛出（NEXTPDF_GFXSTATE_STRICT=1）；在宽松模式下，则改为通过 trigger_error() 发出一条警告。
• Context. getContext() 返回 save_depth（保存过多时为正， 恢复过多时为负）。类型化 getter：getSaveDepth()。
• Recovery. 开发者操作：定位那对不匹配的 save()/restore() 对。

MissingShadingResourceException

• When it is thrown. 当在没有 Shading 资源注册表上下文的情况下调用 ConicGradientRenderer::render() 时。v10.0.0 的破坏性变更移除了先前隐式标记映射的替代路径：调用方必须用一个 ShadingResourceRegistryInterface 来构造渲染器，以便把 /ShadingType 4 间接对象注册到页面的 Shading 资源子字典中（ISO 32000-2 §8.7.4.2 / §8.7.4.3）。消息会指明调用方上下文，并指向 v9.x→v10.0 迁移说明。
• Context. getContext() 返回 context（一个简短的调用方上下文标签， 例如 ConicGradientRenderer::render）。
• Recovery. 库调用方操作：在调用 render() 之前，把一个 Shading 资源注册表实例接入渲染器的构造函数。

线性化（Fast Web View）

LinearizationInvariantException

• When it is thrown. 当 v2 三遍式 Linearizer 检测到它的 MEASURE → PLACE → FILL 断言被违反时：第 3 遍的字节计数与第 1 遍预测的文件长度不匹配（偏移漂移）、线性化字典占位符对于序列化后的宽度过小，或一个 /H [offset length] 提示流偏移与最终输出不匹配。把它浮现出来而非发出一个损坏的 PDF，是一项明确声明的安全保证。
• Context. getContext() 返回 invariant（被违反的不变量名称）、 expected、actual 和 delta（带符号的差值）。类型化 getter： getInvariant()、getExpectedValue()、getActualValue()。
• Recovery. 维护者操作：提交一份缺陷报告——对于所有良构的输入，这些不变量都应当成立。请捕获链接的前一个异常。

LinearizationUnimplementedException

• When it is thrown. 当线性化器特性标志被设为一个被有意禁用的后端时。目前仅对 linearizerVersion === 'v1-noop' 抛出，这是那个紧急降级设置， 它会在运行时拒绝所有线性化尝试，而无需改动代码或重新部署——对于在生产中一键关闭 Fast Web View 很有用。
• Context. getContext() 返回 reason（一段简短的、人类可读的说明）。类型化 getter：getReason()。
• Recovery. 运维 / 发布工程操作：调整配置或升级到一个修复后的后端版本。

符合性与规格不变量

ConformanceViolationException

• When it is thrown. 当某个被请求的特性无法在不破坏文档已声明的 ISO 一致性契约的前提下被发出时，引擎会失败即关闭，而不是写出一个不一致的对象。其规范触发场景是在某个 PDF/A 归档配置文件下出现多媒体 Screen 注释或 Rendition 动作（ISO 32000-2:2020 §12.5.6.18 / §13.2）， 而每一个 PDF/A 部分都禁止它们（ISO 19005 系列）——该文件将无法通过 veraPDF 验证，因此引擎会提前拒绝。
• Context. getContext() 返回 conformance_mode（已声明的模式， 例如 pdfa4）和 feature（被拒绝的特性，例如 Screen annotation）。 二者都是公开的 readonly 属性。原因则是异常消息。
• Recovery. 开发者操作：对于归档输出，去掉该多媒体调用， 或改用一个非归档的一致性配置文件（默认为 ConformanceMode::Plain）。

PdfRViolationException

• When it is thrown. 当某个 PDF/R-1（ISO 23504-1:2020）一致性不变量被违反时，可能发生在值对象构造时（PdfRStrip、PdfRPage、 PdfRDocument 配置文件），或在验证器阶段（PdfRValidator）。它会捕获出问题的规范条款和一行违规描述，以便审计消费方可以把发现路由到正确的 §6 子条款，而无需解析自由文本。
• Context. getContext() 返回 standard（始终为 ISO 23504-1:2020）、 clause（条款路径，例如 6.6.1）和 violation。类型化 getter： getClause()、getViolation()。
• Recovery. 开发者操作：纠正被拒绝的输入，或重新构建该文档以符合所引用的条款。

条码生成

BarcodeException

• When it is thrown. 当条形码生成因无效数据或编码错误而在所有受支持的符号体系（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) 标记， 这样它们就无法被整段复制进日志。
• Context. getContext() 返回 barcode_type（符号体系，例如 QRCODE、 EAN13、CODE128）和 value（被截断的值）。类型化 getter： getBarcodeType()、getValue()。
• Recovery. 开发者操作：纠正条形码数据或符号体系的选择。

BarcodeEncoderNotFoundException

• When it is thrown. 当所请求的编码器类型未知，或其能力门控已关闭时，由 BarcodeEncoderRegistry 抛出。它还实现了 PSR-11 Psr\Container\NotFoundExceptionInterface，因此该注册表是一个符合标准的容器。消息会指明符号体系和原因。
• Context. 不重写 getContext()，因此它返回一个空数组。 type 和 reason 可通过 getType() 和 getReason() getter 以及消息获取。
• Recovery. 开发者操作：注册该编码器，或安装提供它的那个包（例如，用 nextpdf/pro 提供 Micro QR / DotCode / HanXin / JabCode）。

密码学、加密与签名

EncryptionException

• When it is thrown. 当 PDF 加密或解密失败时：AES-256-CBC 加密/解密失败、OpenSSL 错误、无效的 IV 大小、哈希计算失败，以及 UE/OE 值计算错误。通常是缺少或配置错误的 OpenSSL 扩展、无效的密钥材料，或损坏的加密数据。消息会指明操作和算法。
• Context. getContext() 返回 algorithm（例如 AES-256-CBC）和 operation（例如 encrypt、decrypt、key_derivation）。类型化 getter： getAlgorithm()、getOperation()。
• Recovery. 基础设施操作：确保 OpenSSL 可用且配置正确。参见加密与权限。

UnsupportedAlgorithmException

• When it is thrown. 当某个密码学算法无法在当前运行时执行时：所需的 PHP 扩展不可用、底层库缺少该原语、内置的 hash 扩展无法合成某个 SHAKE/XOF 变体，或该算法未在 SignatureAlgorithmRegistry 中注册。引擎绝不能静默地降级到一个更弱的原语，因此它会改为浮现这个异常。静态工厂 nonFipsHostUnderFipsProfile() 会在选择了 RegulatoryProfile::FIPS 但无法确认一个经 FIPS 验证的 OpenSSL 提供者时抛出它（带有算法标识符 regulatory-profile:fips，且 FIPS_ABSENT 和 INDETERMINATE 都会失败即关闭）。
• Context. getContext() 返回 algorithm（名称或 OID，例如 shake256、 Ed25519、AES-256-GCM）和 reason（运维可操作）。类型化 getter： getAlgorithm()、getReason()。
• Recovery. 运维操作：安装缺少的扩展或升级运行时；对于 FIPS 门控，安装一个经 FIPS 验证的 OpenSSL 构建或显式设置 NEXTPDF_FIPS_MODE。开发者操作：通过 SignatureAlgorithmRegistry::register() 注册一个自定义算法描述符。

SignatureException

• When it is thrown. 当某个数字签名操作失败时：证书与私钥处理（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）。这些工厂方法会失败即关闭，而非发出一个被静默降级的签名。
• Context. getContext() 返回 cert_info（主体 DN 或指纹，或为空）、signature_level（所尝试的 PAdES 层级，例如 B-B、B-T、 B-LT、B-LTA），以及 detail（可操作的诊断信息，对于旧式位置参数构造函数为空）。类型化 getter：getCertInfo()、 getSignatureLevel()、getDetail()。
• Recovery. 开发者操作：修正证书/密钥配置。对于能力缺失类的工厂方法，安装所指名的包。关于逐工厂方法的症状与解法条目，参见 签名与时间戳失败。

BlackPointCompensationUnsupportedException

• When it is thrown. 当某个调用方要求空适配器应用一个非 Default 的 ISO 18619 黑点补偿变换时，由 NullBlackPointCompensationTransform::transform() 抛出。对于没有颜色管理后端的环境，空适配器是其安全回退； 在没有真实颜色管理模块的情况下产生一个变换后的采样值，将会静默地错报该转换。与此处大多数条目不同， 它直接继承 \RuntimeException，而非 NextPdfException， 因此现有的 catch (\RuntimeException) 路径仍可正常工作。
• Context. 没有 getContext()；它是一个普通的 \RuntimeException。 细节在消息中。
• Recovery. 开发者操作：注册一个真实的 BlackPointCompensationTransform（LittleCMS、Argyll、纯 PHP），或把 /UseBlackPtComp 限制为 BlackPointCompensation::Default。

文档组装与无障碍

UnsupportedSourceDocumentException

• When it is thrown. 当某个源文档无法被安全地复制进一个合并/拆分输出，且该操作会失败即关闭，而非发出一个损坏或安全受损的结果时。请使用这些具名工厂方法：encrypted()（ISO 32000-2 §7.6——没有密钥就无法复制内容）、signed()（§12.8—— 复制页面会使签名的字节范围失效）、 unsupportedStreamFilter()（对象图读取器无法往返的过滤器）、multipleInteractiveForms()（一个已记录的限制：多于一个源携带了非空的 /AcroForm，§12.7），以及 splitWithInteractiveForm()（一个已记录的限制：对一个含表单的源进行页面子集化会使控件成为孤儿）。直接继承 \RuntimeException， 而非 NextPdfException。
• Context. 没有 getContext()；它是一个普通的 \RuntimeException。原因和受影响的对象编号都在消息中指明。
• Recovery. 开发者操作：先解密源，或提供密钥； 对于已签名的源，改为在合并之后再签名；对于多表单的合并，扁平化或移除除一个源以外的所有源的表单字段；对于含表单的拆分， 在拆分之前先扁平化该表单。

InvalidBcp47TagException

• When it is thrown. 当某个候选语言标签在 RFC 5646 §2.1 ABNF 下格式错误，或未通过精选注册表查找时，由 Bcp47Validator::validate() 抛出。它特定于 BCP-47 / ISO 14289-2:2024 §8.4.4， 与 InvalidConfigException 不同，以便位于无障碍接缝下游的调用方可以捕获一个窄类型。谓词对 Bcp47Validator::isWellFormed() / isValid() 仍然是那些偏好用分支而非异常的调用方所用的向后兼容返回值表面。
• Context. getContext() 返回 tag（与所提供的完全一致的候选） 和 reason（一个稳定的、机器可读的拒绝代码，例如 empty-string、 well-formed-shape、unregistered-primary、duplicate-variant）。类型化 getter：getTag()、getReason()。
• Recovery. 开发者操作：把语言标签纠正为一个良构、 已注册的 BCP-47 标签。参见 字体与标记。

FormFieldAccessibilityException

• When it is thrown. 当某个交互式表单字段会依赖一个合成的 （非作者提供的）无障碍名称，而同时正在产生一个启用了严格无障碍字段名称强制的 PDF/UA 文档时。默认的 PDF/UA 输出会把一个合成的回退名称发出到控件的 /Contents 中，使得字段绝不会无名；而严格模式则改为要求作者提供一个有意义的名称 （一个工具提示，或一个无动作按钮的标题），以便屏幕阅读器用户能获得一段真实的描述（ISO 14289-2:2024 §8.10.2）。
• Context. 不重写 getContext()，因此它返回一个空数组。 $fieldId 是一个公开的 readonly 属性；原因在消息中。
• Recovery. 开发者操作：在产生一个严格的 PDF/UA 文档之前，为所指名的字段提供一个工具提示 / 无障碍名称，或禁用严格模式。 参见 PDF/A 与 PDF/UA 验证。

VendorExtensionRegistryConflictException

• When it is thrown. 当某个调用方用一份与已注册元数据不一致的描述，重新注册一个已知的 PDF 开发者扩展厂商前缀 （ISO 32000-2:2020 §7.12.1）时，由 VendorExtensionRegistry::register() 抛出。描述符是仅追加且会进行冲突检测的；这个类型化的异常取代了一个通用的 \RuntimeException，以便调用方可以捕获这个具体的类。
• Context. getContext() 返回 prefix、existing_description 和 attempted_description。类型化 getter：getPrefix()、 getExistingDescription()、getAttemptedDescription()。
• Recovery. 开发者操作：用现有描述注册该前缀， 或使用一个不同的前缀；不要覆盖已注册的元数据。

审计导出

AuditExportException

• When it is thrown. 当审计导出包装配、可追溯性矩阵生成或 schema 投影在运行时失败时。涵盖针对 claims.json / manifest.json 的 I/O、规范包的 JSON 编码/解码， 以及 AuditExporter::projectToV1() 向后兼容路径上的 schema 版本不匹配。消息会指明所处阶段、已知时的产物，以及细节。
• Context. getContext() 返回 stage（例如 read_claims、 encode_bundle、project_v1）、detail 和 artefact（触发该失败的路径或 schema_version）。类型化 getter：getStage()、 getDetail()、getArtefact()。
• Recovery. 合规 / DevOps 操作：核实输入产物路径、 从一次干净的运行重新生成 claims.json，或在重新尝试导出之前重建清单。

违规值对象

这些不是异常。它们是引擎返回的不可变值对象，用来描述单个违规；它们不携带 getContext()。

ComplianceViolation

• What it is. 一个 final readonly 值对象，表示由某个外部验证器 （veraPDF 或等价物）报告的一条规则失败，包括 ISO 条款引用以及 PDF 结构内的位置。
• Fields. 公开的 readonly 属性：ruleId（验证器规则标识符， 例如 6.1.2-1）、clause（ISO 条款引用，例如 ISO 19005-1:2005, 6.1.2）、severity（例如 error、warning）、location （PDF 结构内的对象路径），以及 message（人类可读的描述）。
• Use. 检查由某个合规验证器返回的集合；按 severity 和 clause 路由或显示每个条目。参见 PDF/A 与 PDF/UA 验证。

RuleViolation

• What it is. 一个 final readonly 值对象，表示一条 Schematron / EN 16931 业务规则违规，由 SchematronRunnerInterface::runRules() 返回，并聚合在 ValidationResult::$ruleViolations 内。稳定性为实验性。
• Fields. 公开的 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）。
• Use. 检查验证结果上的集合；按 severity、ruleId 和定位符路由或显示每个条目。

另请参阅

• Error reference index
• Knowledge base index
• Signature and timestamp failures
• Encryption and permissions
• Fonts and tagging
• PDF/A and PDF/UA validation