トラブルシューティング・ナレッジベース

このナレッジベースの対象範囲

このナレッジベースでは、観測された失敗を、その原因と解決策に対応付けています。各エントリは推測ではなく、エンジン自身の例外クラス、失敗パスのテスト、ソースコード上のガードに基づいています。特定の失敗を引き起こすコードパスがエンジンに存在しない場合、このナレッジベースでそれを作り出すことはありません。

このナレッジベースは、4 つのトピックページで構成されています。

署名検証 — 無効な署名、不完全なチェーン、失効状態不明、タイムスタンプの失敗。
PDF/A および PDF/UA の検証 — 出力インテントの欠落、タグ付けされていないコンテンツ、言語の欠落、埋め込みフォントの失敗。
フォントとタグ付け — フォントが見つからない、サブセット化、CJK のカバレッジ、構造ツリーの問題。
暗号化と権限 — 復号の失敗と、権限フラグの境界。

エントリの読み方

各エントリは 5 つの部分で構成されています。

症状 — 観測される内容です。例外クラス、メッセージの断片、または後続のバリデーターによる判定結果を示します。
考えられる原因 — エンジンが報告する、入力または構成上の状態です。
証拠 / 診断 — 原因を確認する方法です。ここでは、その挙動を示す厳密な例外クラス、getContext() のフィールド、またはテストを示します。これにより、推測ではなく検証に基づいて判断できます。
解決策 — 原因を取り除くための手順です。順序立てた手順として記述しています。
関連情報 — 次に参照すべきモジュールリファレンスページ、または関連エントリです。

例外の種類による失敗の特定

NextPDF は、文字列のエラーコードではなく PHP クラスでエラーを識別します。例外クラスに NPDF-#### という定数はありません。対象を絞って対応するにはリーフ例外をキャッチし、構造化された診断フィールドを取得するには ContextAwareExceptionInterface::getContext() を読み取ってください。基底型は NextPDF\Exception\NextPdfException です。セキュリティ関連の失敗では、これに加えて NextPDF\Security\Exception\SecurityException が使用されます。

完全な階層構造とキャッチ順序のルールについては、例外リファレンスを参照してください。

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

範囲と境界

このナレッジベースでは、エンジン内部における失敗の検出と報告について説明します。veraPDF や callas などの外部バリデーターによる適合性判定は扱いません。これらのツールは独自のルールセットを適用します。ドキュメントをプロファイル内に保つためにエンジンが操作を拒否する場合 — たとえば、PDF/A での暗号化を拒否する場合 — 該当するエントリでは、その根拠となる条項と、それを強制する例外を引用します。

トラブルシューティング・ナレッジベース

このナレッジベースの対象範囲

エントリの読み方

例外の種類による失敗の特定

範囲と境界

関連項目