コアおよび一般のエラー

対象範囲

これらのエントリは、NextPDF が送出するコアおよび汎用の例外を扱います。 ほとんどは基底の NextPdfException を継承し、それ自体は \RuntimeException を継承して ContextAwareExceptionInterface を実装します。そのインターフェイスは 1 つのメソッド getContext(): array を公開し、ログまたは APM ペイロードへのシリアライズに安全なプリミティブからなるフラットな snake_case のマップを返します。

NextPdfException ファミリーは単一の catch (NextPdfException $e) で捕捉してください。 このセット内で \RuntimeException を直接継承する少数の低レベルエラー（以下に列挙）をカバーするために、catch (\RuntimeException $e) も追加してください。基底の NextPdfException::getContext() は空の配列を返します。サブクラスはそれをオーバーライドしてドメインフィールドを追加します。クラスが getContext() をオーバーライドしない場合は、 空の配列を継承し、代わりに診断の詳細はメッセージと型付きゲッターに存在します。

このセットの 4 つの型は NextPdfException を継承 しません。 BlackPointCompensationUnsupportedException と UnsupportedSourceDocumentException は \RuntimeException を直接継承し （\RuntimeException として捕捉してください）、ComplianceViolation と RuleViolation は値オブジェクトであり、例外ではありません。エンジンが返すエラーおよび違反データをモデル化するため、ここで記載しています。

基底例外

NextPdfException

• 概要。 NextPDF core とその拡張パッケージが送出するすべての例外の abstract 基底クラスです。\RuntimeException を継承し ContextAwareExceptionInterface を実装します。この単一型を捕捉すれば、あらゆるライブラリエラーを捕捉できます。
• コンテキスト。 基底の getContext() は空の配列を返します。サブクラスはそれをオーバーライドしてドメイン固有のフィールドを返します。
• 復旧。 直接送出されません。catch-all 型として使用し、 具象サブクラスに分岐して個別に処理してください。

構成と機能ゲーティング

InvalidConfigException

• 送出される条件。 Config の値または値の組み合わせが不正な場合。必須設定の欠落、相互排他的なオプション、許容範囲外の値などです。これは開発者エラーを示します。すなわち呼び出し側のコードが修正してから再試行すべき構成を渡したことを意味します。メッセージはキー、期待される型または範囲、そして渡された値の実際のデバッグ型を報告します。
• コンテキスト。 getContext() は config_key、given_value、 expected_type を返します。型付きゲッター: getConfigKey()、getGivenValue()、 getExpectedType()。
• 復旧。 開発者アクション: NextPDF を再び呼び出す前に、指定された構成キーを期待される型または範囲の値に修正してください。

NotImplementedException

• 送出される条件。 public API のエントリポイントに到達したものの、その実装が現在のリリースで意図的に存在しない場合。bisect 以前の呼び出し側に対して、サイレントな no-op ではなく、明示的で対処可能な失敗を返すために存在する deprecated シムに使用されます。メッセージは機械的に grep 可能な feature ラベルと followUp 参照（不具合 ID、追跡用アンカー、 またはスプリント名）を組み合わせます。
• コンテキスト。 getContext() をオーバーライドしないため、空の配列を返します。 $feature と $followUp の値は public readonly プロパティであり、メッセージに埋め込まれています。
• 復旧。 ライブラリ呼び出し側アクション: 呼び出しを削除するか、指定された follow-up を実装する将来のリリースにピン留めしてください。

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() は親の strict モードフィールド （cssDeviation、excId、chunkSha256、location）を layoutGrid と layoutSubgrid のブール値とマージします。location は Config::validate() であり、 cssDeviation はフラグのペアをエンコードします。
• 復旧。 ライブラリ呼び出し側アクション: layoutSubgrid とともに layoutGrid を有効化するか、layoutSubgrid を無効化してください。

IncompatibleRenderingModeException

• 送出される条件。 Config のビルド時に、CssRenderingMode と CssLayoutMode のペアがモードマトリクスの互換セルの外に出た場合。 今日唯一禁止されているペアは CssRenderingMode::Safe + CssLayoutMode::Retained です。Safe はすべての Phase 4+ 機能を強制的に無効化し、 retained モードのフォーマッティングコンテキスト（Grid、Subgrid、@container）に消費者がいなくなるため、サイレントに機能低下することを許すのではなく組み合わせを拒否します。StrictModeViolation を継承します。
• コンテキスト。 getContext() は親の strict モードフィールドを mode1 （レンダリングモードの値）と mode2（レイアウトモードの値）とマージします。 cssDeviation はモードのペアをエンコードし、location は Config::validate() です。
• 復旧。 ライブラリ呼び出し側アクション: ロールバックには Safe + Streaming を選択するか、 Grid / Subgrid / Container Queries には Retained と Safe 以外のレンダリングモード （Normal / Strict / Audit）を選択してください。

StrictModeViolation

• 送出される条件。 CssRenderingMode::Strict の下で送出される、あらゆる仕様逸脱例外の abstract 基底クラスです。strict モードでは、登録済みの EXC-NNN 例外エントリにリンクされていない検出済み CSS 逸脱が、検出ポイントでこのクラス（またはサブクラス）のインスタンスを送出します。直接送出されません。 IncompatibleFeatureFlagsException と IncompatibleRenderingModeException を参照してください。
• コンテキスト。 getContext() は ADR-023 の 4 つのフィールドを返します。cssDeviation （逸脱した構成要素の短いラベル）、excId（登録されている場合はレジストリ識別子、 それ以外は null）、chunkSha256（既知の場合は仕様引用のチャンクハッシュ、 それ以外は null）、そして location（呼び出し側が読める起点、それ以外は null）。
• 復旧。 ライブラリ呼び出し側アクション: 逸脱を新しいサインオフ済みの EXC-NNN エントリとして登録するか、レンダラーを修正して逸脱を取り除いてください。

HTML および CSS 入力

HtmlParsingException

• 送出される条件。 HTML 入力のパースまたは DOM 構築が失敗した場合。 不正な charset 宣言、入力サイズ制限の違反、過剰なネスト深度、要素数のオーバーフロー、行数の最大値などのテーブル構造エラーです。CSS 固有のリソース枯渇は、代わりに CssParserLimitExceededException と CssResolutionBudgetExceededException が報告します。
• コンテキスト。 getContext() は html_snippet（問題のある HTML の短い、切り詰められた抜粋）、position（バイトオフセット、不明な場合は -1）、 rule（違反したパーサー制約）を返します。型付きゲッター: getHtmlSnippet()、 getPosition()、getRule()。
• 復旧。 開発者アクション: HTML 入力を簡素化するか、パーサーの制限を調整してください。

CssParserLimitExceededException

• 送出される条件。 CSS 入力が構成済みのパーサー安全制限を超えた場合。名前付きコンストラクターを通じて 2 つのカテゴリーがカバーされます。 forByteLimit()（安全な正規表現処理にはスタイルシートが大きすぎる）と forNestingDepth()（CSS のネスト再帰が深すぎる）です。どちらのメッセージも実際の値と制限を示します。
• コンテキスト。 getContext() は limit_type（byte または nesting_depth）、 actual、limit を返します。
• 復旧。 開発者アクション: スタイルシートをより小さなシートに分割するか、 ネスト深度を削減するか、構成済みの制限を引き上げてください。

CssResolutionBudgetExceededException

• 送出される条件。 CSS :has() の解決がトラバーサル予算を超えた場合。2 パスの :has() リゾルバーは厳密なノード訪問予算を強制し、 病的なセレクターがドキュメントの二次的な走査を引き起こすことを防ぎます。 訪問総数が制限を超えると、スタイルシートは複雑すぎるとして拒否されます。メッセージは訪問数と予算を示します。
• コンテキスト。 getContext() は visits と budget を返します。型付きゲッター: getVisits()、getBudget()。
• 復旧。 開発者アクション: セレクターの複雑さを軽減するか、構成済みの予算を引き上げてください。

フォントと画像

FontNotFoundException

• 送出される条件。 ファイルシステムレベルでフォントファイルを特定または読み取りできない場合。 要求されたファミリーまたはパスが存在しない、 読み取り可能でない、または構成済みのフォントディレクトリにアクセスできない場合です。フォントデータ自体は有効である可能性があります。これは到達できないことのみを示します。メッセージは検索したパスを列挙します。
• コンテキスト。 getContext() は font_name、search_paths（リスト）、 fallback_attempted（ブール値）を返します。型付きゲッター: getFontName()、 getSearchPaths()、wasFallbackAttempted()。
• 復旧。 開発者アクション: フォントパスを確認してください。インフラストラクチャアクション: フォントファイルまたはディレクトリのファイル権限を修正してください。

FontParsingException

• 送出される条件。 フォントファイルは見つかったものの、その内容が使用できない場合。破損している、サポートされていない形式である、または必須テーブルが欠落しています。 TrueType、Type 1、CFF、OpenType のパース中の構造検証失敗をカバーします。切り詰められたヘッダー、不正なテーブルディレクトリ、必須テーブル（head、hhea、OS/2）の欠落、アンパックエラー、サイズ違反などです。メッセージはファイルとパースエラーを示します。
• コンテキスト。 getContext() は font_file と parse_error を返します。型付きゲッター: getFontFile()、getParseError()。
• 復旧。 開発者アクション: フォントファイルを有効なものに置き換えてください。

ImageProcessingException

• 送出される条件。 画像をデコードできない、サポートされていない形式である、または GD/Imagick の処理に失敗した場合。認識できないマジックバイト、破損した JPEG データ、サポートされていない MIME タイプ、ファイルサイズ制限の違反、GD のリソース割り当て失敗などです。画像はアクセス可能でしたが、そのピクセルデータを埋め込み用に抽出できませんでした。
• コンテキスト。 getContext() は image_path（インラインデータの場合は空）、 format（検出または期待される形式、例: jpeg、png、unknown）、 operation（例: decode、resize、embed）を返します。型付きゲッター: getImagePath()、getFormat()、getOperation()。
• 復旧。 開発者アクション: 有効でサポートされている画像ファイルを指定してください。

出力、レイアウト、シリアライズ

CompressionException

• 送出される条件。 FlateDecode（zlib）の圧縮または解凍が失敗した場合。コンテンツストリーム、フォントデータ、 ページコンテンツ、添付データ、クロスリファレンスストリームに対する gzcompress/gzuncompress の失敗です。通常は破損した入力ストリーム、メモリ不足、または zlib 拡張モジュールの欠落です。
• コンテキスト。 getContext() は algorithm（フィルター名、例: FlateDecode、LZWDecode）と stream_length（バイト長、不明な場合は -1）を返します。型付きゲッター: getAlgorithm()、getStreamLength()。
• 復旧。 インフラストラクチャアクション: ext-zlib が読み込まれており、メモリが十分であることを確認してください。

WriterException

• 送出される条件。 PDF のシリアライズ、線形化、または I/O 出力が失敗した場合。PdfWriter のストリーム書き込みエラー、クロスリファレンステーブルの破損、 ヘッダー/トレーラー生成の失敗、オブジェクト参照の解決失敗、ファイル書き込みエラー、出力バッファのオーバーフローなどです。有効なインメモリのドキュメントを有効なバイトストリームにシリアライズできませんでした。メッセージはステージを示します。
• コンテキスト。 getContext() は output_path（文字列出力の場合は空）と writer_state（ステージ、例: header、body、xref、trailer）を返します。 型付きゲッター: getOutputPath()、getWriterState()。
• 復旧。 インフラストラクチャアクション: ディスク容量、ファイル権限、 出力ストリームを確認してください。

PageLayoutException

• 送出される条件。 ページレイアウトの制約を満たせない場合。 カラムレイアウトの違反（幅不足、不正なカラム数）、ページ境界を越えるコンテンツのオーバーフロー、マージンの競合などです。要求されたレイアウトは指定されたページ寸法とコンテンツに対して幾何学的に不可能です。 メッセージは、判明している場合はページ番号と、違反した制約を示します。
• コンテキスト。 getContext() は page_number（1 始まり、不明な場合は 0）と constraint を返します。型付きゲッター: getPageNumber()、 getConstraint()。
• 復旧。 開発者アクション: ページサイズ、マージン、カラム設定、またはコンテンツを調整してください。

TemplateException

• 送出される条件。 TemplateManager における PDF テンプレートのインポートまたは再利用の操作が失敗した場合。不正なテンプレートの状態遷移（テンプレートの開始または終了を順序外で行うこと）、存在しないテンプレートの参照、テンプレートのシリアライズ中のストリーム圧縮失敗などです。メッセージは操作と、割り当て済みの場合はテンプレート ID を示します。
• コンテキスト。 getContext() は template_id（まだ割り当てられていない場合は空）と operation（例: begin、end、use、serialize）を返します。型付きゲッター: getTemplateId()、getOperation()。
• 復旧。 開発者アクション: テンプレートの使用シーケンスまたはソース PDF を修正してください。

コンテンツストリームの不変条件

ContentStreamBalanceException

• 送出される条件。 ContentStreamBuilder が、ストリームのクローズ時に （または不変条件を早期にアサートする場合は途中で）演算子のペアの不均衡を検出した場合。 balance 不変条件に失敗した深度カウンターを捕捉するため、ログにより、対応する 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 を返します。型付きゲッター: getGraphicsDepth()、getTextBlockDepth()、getMarkedContentDepth()、 getOffendingOperator()。
• 復旧。 開発者アクション: 構成要素を開いて閉じなかったエミッターを特定してください。

GraphicsStateBalanceException

• 送出される条件。 PDF コンテンツストリームが不均衡な q/Q 演算子でクローズした場合。ISO 32000-2:2020 §8.4.2 は、各グラフィックス状態の保存（q）がストリーム終了前に正確に 1 つの復元（Q）と対応することを要求します。不均衡は、変換、クリッピングパス、色、レンダリングインテントを後続のページまたは Form XObject にリークさせます。strict グラフィックス状態チェックが有効な場合（NEXTPDF_GFXSTATE_STRICT=1）のみ送出されます。relaxed モードでは、代わりに trigger_error() を通じて警告が発行されます。
• コンテキスト。 getContext() は save_depth（保存が多すぎる場合は正、 復元が多すぎる場合は負）を返します。型付きゲッター: 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 の 3 パス Linearizer が、その MEASURE → PLACE → FILL のアサーションが破られたことを検出した場合。Pass 3 のバイト数が Pass 1 で予測したファイル長と一致しない（オフセットのずれ）、線形化ディクショナリのプレースホルダーがシリアライズ後の幅に対して小さすぎる、または /H [offset length] ヒントストリームのオフセットが最終出力と一致しない場合です。壊れた PDF を出力するのではなくこれを表面化させることは、明示された安全性保証です。
• コンテキスト。 getContext() は invariant（破られた不変条件の名前）、 expected、actual、delta（符号付きの差分）を返します。型付きゲッター: getInvariant()、getExpectedValue()、getActualValue()。
• 復旧。 メンテナーアクション: バグレポートを提出してください。これらの不変条件は、 整形式のすべての入力に対して保持されるべきものです。チェーンされた previous 例外を捕捉してください。

LinearizationUnimplementedException

• 送出される条件。 線形化機能フラグが、意図的に無効化されたバックエンドに設定されている場合。現在は linearizerVersion === 'v1-noop' に対してのみ送出されます。これは、コード変更や再デプロイなしに、すべての線形化の試みを実行時に拒否する緊急ダウングレード設定であり、本番環境で Fast Web View を kill-switch するのに役立ちます。
• コンテキスト。 getContext() は reason（短い人間が読める説明）を返します。型付きゲッター: 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）を返します。 どちらも public 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 を返します。型付きゲッター: 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（切り詰められた値）を返します。型付きゲッター: getBarcodeType()、getValue()。
• 復旧。 開発者アクション: バーコードデータまたはシンボロジーの選択を修正してください。

BarcodeEncoderNotFoundException

• 送出される条件。 要求されたエンコーダータイプが不明な場合、またはその機能ゲートが閉じている場合に、BarcodeEncoderRegistry から送出されます。PSR-11 Psr\Container\NotFoundExceptionInterface も実装するため、レジストリは標準準拠のコンテナーです。メッセージはシンボロジーと理由を示します。
• コンテキスト。 getContext() をオーバーライドしないため、空の配列を返します。 type と reason は getType() および getReason() ゲッターとメッセージを通じて利用できます。
• 復旧。 開発者アクション: エンコーダーを登録するか、それを提供するパッケージをインストールしてください（例: Micro QR / DotCode / HanXin / JabCode の場合は nextpdf/pro）。

暗号、暗号化、署名

EncryptionException

• 送出される条件。 PDF の暗号化または復号が失敗した場合。AES-256-CBC の暗号化/復号の失敗、OpenSSL エラー、不正な IV サイズ、ハッシュ計算の失敗、UE/OE 値計算のエラーなどです。通常は OpenSSL 拡張モジュールの欠落または誤設定、 不正な鍵素材、または破損した暗号化データです。メッセージは操作とアルゴリズムを示します。
• コンテキスト。 getContext() は algorithm（例: AES-256-CBC）と operation（例: encrypt、decrypt、key_derivation）を返します。型付きゲッター: getAlgorithm()、getOperation()。
• 復旧。 インフラストラクチャアクション: OpenSSL が利用可能で正しく構成されていることを確認してください。Encryption and permissionsを参照してください。

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（オペレーターが対処可能）を返します。型付きゲッター: 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（対処可能な診断、レガシーの位置引数コンストラクターでは空）を返します。型付きゲッター: getCertInfo()、 getSignatureLevel()、getDetail()。
• 復旧。 開発者アクション: 証明書/鍵の構成を修正してください。 機能欠落のファクトリについては、指定されたパッケージをインストールしてください。ファクトリごとの症状と解決のエントリについては、 Signature and timestamp failures を参照してください。

BlackPointCompensationUnsupportedException

• 送出される条件。 呼び出し側が null アダプターに Default 以外の ISO 18619 black-point 補償変換の適用を求めた場合に、NullBlackPointCompensationTransform::transform() から送出されます。null アダプターは色管理バックエンドのない環境向けの安全なフォールバックです。実際の色管理モジュールなしに変換済みのサンプルを生成すると、変換をサイレントに誤報告することになります。ここでのほとんどのエントリと異なり、これは NextPdfException ではなく \RuntimeException を直接継承するため、既存の catch (\RuntimeException) パスは引き続き機能します。
• コンテキスト。 getContext() はありません。素の \RuntimeException です。詳細はメッセージにあります。
• 復旧。 開発者アクション: 実際の BlackPointCompensationTransform（LittleCMS、Argyll、pure-PHP）を登録するか、 /UseBlackPtComp を BlackPointCompensation::Default に制限してください。

ドキュメントの組み立てとアクセシビリティ

UnsupportedSourceDocumentException

• 送出される条件。 ソースドキュメントをマージ/分割出力に安全にコピーできず、 操作が破損した、またはセキュリティが損なわれた結果を出力するのではなくフェイルクローズで動作する場合。名前付きファクトリを使用してください。encrypted()（ISO 32000-2 §7.6 — 鍵なしではコンテンツをコピーできない）、signed()（§12.8 — ページをコピーすると署名のバイト範囲が無効になる）、 unsupportedStreamFilter()（オブジェクトグラフリーダーがラウンドトリップできないフィルター）、multipleInteractiveForms()（文書化された制限: 複数のソースが空でない /AcroForm を持つ、§12.7）、そして splitWithInteractiveForm()（文書化された制限: フォームを持つソースをページサブセット化するとウィジェットが孤立する）です。NextPdfException ではなく \RuntimeException を直接継承します。
• コンテキスト。 getContext() はありません。素の \RuntimeException です。原因と影響を受けるオブジェクト番号はメッセージに記載されます。
• 復旧。 開発者アクション: ソースを先に復号するか鍵を指定してください。 署名済みのソースについては、代わりにマージ後に署名してください。複数フォームのマージについては、フォームフィールドを 1 つのソースを除いてすべてフラット化または削除してください。フォームを持つ分割については、分割前にフォームをフラット化してください。

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）を返します。型付きゲッター: getTag()、getReason()。
• 復旧。 開発者アクション: 言語タグを、整形式で登録済みの BCP-47 タグに修正してください。 Fonts and taggingを参照してください。

FormFieldAccessibilityException

• 送出される条件。 インタラクティブなフォームフィールドが、合成された （作成者が提供していない）アクセシブル名に依存しつつ、厳格なアクセシブルフィールド名の強制を有効にした PDF/UA ドキュメントを生成しようとする場合。デフォルトの PDF/UA 出力は、フィールドが決して無名にならないよう、合成フォールバック名をウィジェットの /Contents に出力します。一方 strict モードでは、スクリーンリーダーのユーザーが実際の説明を得られるよう、作成者が意味のある名前（ツールチップ、またはアクションのないプッシュボタンのキャプション）を提供することを要求します（ISO 14289-2:2024 §8.10.2）。
• コンテキスト。 getContext() をオーバーライドしないため、空の配列を返します。 $fieldId は public readonly プロパティであり、理由はメッセージです。
• 復旧。 開発者アクション: strict な PDF/UA ドキュメントを生成する前に、指定されたフィールドにツールチップ / アクセシブル名を提供するか、strict モードを無効化してください。 PDF/A and PDF/UA validationを参照してください。

VendorExtensionRegistryConflictException

• 送出される条件。 呼び出し側が、既知の PDF 開発者拡張のベンダープレフィックス（ISO 32000-2:2020 §7.12.1）を、すでに登録されているメタデータと食い違う説明で再登録した場合に、VendorExtensionRegistry::register() から送出されます。ディスクリプターは追記専用で競合検出されます。型付きの例外は、呼び出し側がこの特定のクラスを捕捉できるよう、汎用の \RuntimeException を置き換えたものです。
• コンテキスト。 getContext() は prefix、existing_description、 attempted_description を返します。型付きゲッター: 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）を返します。型付きゲッター: getStage()、 getDetail()、getArtefact()。
• 復旧。 準拠 / DevOps アクション: 入力成果物のパスを確認するか、 クリーンな実行から claims.json を再生成するか、エクスポートを再試行する前にマニフェストを再構築してください。

違反値オブジェクト

これらは例外ではありません。エンジンが個々の違反を記述するために返す不変の値オブジェクトであり、getContext() を保持しません。

ComplianceViolation

• 概要。 外部バリデーター（veraPDF または同等のもの）が報告した 1 つのルール失敗を表す final readonly 値オブジェクトです。ISO 条項参照と PDF 構造内の位置を含みます。
• フィールド。 public 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 and PDF/UA validationを参照してください。

RuleViolation

• 概要。 1 つの Schematron / EN 16931 ビジネスルール違反を表す final readonly 値オブジェクトです。SchematronRunnerInterface::runRules() が返し、 ValidationResult::$ruleViolations 内に集約されます。安定性は実験的です。
• フィールド。 public readonly プロパティ: ruleId（EN 16931 識別子、例: BR-{n}、BR-CO-{n}、BR-CL-{n}、BR-DEC-{n}、またはティア固有のパック）、 severity（RuleSeverity enum）、message（ルールテキスト、en-GB）、xpath （埋め込み XML への XPath、ドキュメント全体のルールでは null）、そして semanticPath（ドット記法の BG/BT パス、例: BG-22.BT-106、構造的違反では null）。
• 用途。 検証結果のコレクションを検査し、各エントリを severity、ruleId、ロケーターでルーティングまたは表示してください。

関連項目

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