ランタイムおよびサポートのエラー
これらのエントリは、ランタイムサポート層が送出する例外を解説します。 機能低下ポリシー、cURL バックの HTTP トランスポート、レジリエンスのサーキットブレーカー、Security Information and Event Management（SIEM）エミッター、 レンダーマニフェスト、PDF 検査、そしてカオスエンジニアリングサブシステムです。
すべての NextPDF 例外は NextPdfException を継承し、それは
ContextAwareExceptionInterface を実装して、構造化された診断ログのための getContext(): array を公開します。サブクラスは、getContext() をオーバーライドした場合にのみその配列を設定します。基底は空の配列を返します。このページの 3 つの例外
（DegradedException、CircuitBreakerOpenException、InspectException）は PHP の
RuntimeException を直接継承し、getContext() ではなく public な readonly
プロパティを通じてデータを公開します。以下の各エントリでは、クラスが保持する正確なプロパティまたはコンテキストキーを、ソースから取って示します。
機能低下ポリシー
「機能低下ポリシー」という見出しのセクションDegradedException
「DegradedException」という見出しのセクション- 送出される条件。 レンダリングパイプラインが、アクティブな機能低下ポリシーに違反する機能低下した能力に遭遇した場合。
DegradationPolicy::Strictの下では、あらゆる高影響の機能低下 （ComplianceRisk、SemanticLoss、またはBlocking）がこれを送出します。DegradationPolicy::Balancedの下では、Blockingの影響のみがこれを送出します。 - クラス。
RuntimeExceptionを直接継承します（NextPdfExceptionではない）。したがってgetContext()を保持しません。 - 保持するデータ。 2 つの public な
readonlyプロパティ。$capability（拒否を引き起こしたCapability値オブジェクト。そのid、status、reason、fallbackTarget、impactを含む）と$policy（拒否時にアクティブだったDegradationPolicy）。メッセージはFeature "<id>" is <status>: <reason> (policy: <policy>)という形です。 - 復旧。
$capabilityを検査して、欠落している機能とその原因を特定してください。その能力が必要とするコンポーネントをインストールするか、より低影響の構成を受け入れるか、 機能低下がユースケースに対して許容できる場合はStrictからBalancedにポリシーを緩めてください。ユーザー向けのメッセージングを駆動するには、$capability->isAvailable()/isDegraded()を呼び出してください。
HTTP トランスポート
「HTTP トランスポート」という見出しのセクションこれら 3 つの例外は、cURL バックの PSR-18 クライアントとそのセキュリティ対応デコレーターに由来します。最初の 2 つは NextPdfException を継承しますが
getContext() をオーバーライドしないため、その getContext() は空の配列を返します。
診断データは、PSR-18 の getRequest() アクセサーとチェーンされた previous の throwable を通じて到達します。
CurlNetworkException
「CurlNetworkException」という見出しのセクション- 送出される条件。 ネットワークレベルの障害により HTTP リクエストを完了できない場合。Domain Name System（DNS）の解決失敗、 接続タイムアウト、または Transport Layer Security（TLS）ハンドシェイクエラーです。これはまた、セキュリティ拒否（Server-Side Request Forgery の拒否、DNS リバインディングの拒否、または拒否されたリダイレクト）に対してセキュリティ対応デコレーターが送出するクラスでもあります。
- クラス。 PSR-18
Psr\Http\Client\NetworkExceptionInterfaceを実装します。 - 保持するデータ。
getRequest()は失敗したRequestInterfaceを返します。 発生元のトランスポートエラーは、存在する場合、チェーンされた previous の throwable です。getContext()は空の配列（基底のデフォルト）を返します。 - 復旧。 ネットワーク障害は一時的なことがあります。リクエストが冪等であれば、バックオフを伴って再試行してください。 セキュリティ拒否は一時的ではなく、フェイルクローズで動作する必要があります。再試行せず、代わりにターゲット URL または SSRF ポリシーを修正してください。 両者を区別するには、メッセージと previous の throwable を読み取ってください。
CurlRequestException
「CurlRequestException」という見出しのセクション- 送出される条件。 リクエスト自体が不正であるために送信できない場合。 例えば不正な URL や、ネットワーク呼び出しの前に SSRF 検証に失敗したリクエストです。
- クラス。 PSR-18
Psr\Http\Client\RequestExceptionInterfaceを実装します。 - 保持するデータ。
getRequest()は問題のあるRequestInterfaceを返します。 根本原因は、存在する場合、チェーンされた previous の throwable です。getContext()は空の配列を返します。 - 復旧。 これは呼び出し側の入力またはポリシーの不具合であり、一時的な障害ではありません。変更せずに再試行しないでください。リクエストの URL、ヘッダー、または本文を修正するか、ターゲットが正当に許可されている場合は SSRF 許可リストを調整してから、リクエストを再発行してください。
TransientHttpException
「TransientHttpException」という見出しのセクション- 送出される条件。
SecurityAwareHttpClientの内部で、真に一時的な内部トランスポートの障害（内部 PSR-18 クライアントが送出する DNS、接続、またはタイムアウト）を、限定された再試行予算の対象としてマークするために送出されます。これはデコレーターの再試行ループが認識する唯一の再試行可能なクラスです。ラップされていない例外（デコレーターが送出したセキュリティ拒否）は致命的として扱われます。 - クラス。 PSR-18
Psr\Http\Client\NetworkExceptionInterfaceを実装します。@internalとマークされています。これはSecurityAwareHttpClientの内部で完全に作成およびアンラップされ、デコレーターの外に漏れることは決してありません。 - 保持するデータ。
getRequest()は失敗したリクエストを返します。元の内部トランスポートのClientExceptionInterfaceは、チェーンされた previous の throwable（getPrevious()）として保持され、再試行予算が尽きると呼び出し側にそのまま再表面化されるため、public な PSR-18 コントラクトは変わりません。getContext()は空の配列を返します。 - 復旧。 アプリケーションコードはこの型を直接捕捉しません。再試行予算が尽きた後にデコレーターが返す、再表面化された内部例外を捕捉し、 繰り返される一時的な失敗を上流の可用性問題として扱ってください。
レジリエンス
「レジリエンス」という見出しのセクションCircuitBreakerOpenException
「CircuitBreakerOpenException」という見出しのセクション- 送出される条件。
CircuitBreakerState::Open状態のCircuitBreakerが、 あらゆる下流の呼び出しの前に、呼び出しを fail-fast で拒否した場合。これは、呼び出し側が「リモートサービスが今すぐ到達不能である」（機能低下する価値のある一時的なトランスポート障害）と「この呼び出しで接続プールが枯渇していたはずである」（fail-fast、ネットワークは試みない）とを区別できるよう存在します。後者は、Public Key Infrastructure （PKI）クライアントに必要な、バッチサービス拒否の緩和です。 - クラス。
RuntimeExceptionを直接継承するため、getContext()を保持しません。 - 保持するデータ。 2 つの public な
readonlyプロパティ。$breakerName（開いたブレーカーの識別子）と$secondsUntilHalfOpen（ブレーカーが half-open に遷移するまでに残るおおよそのクールダウン）。メッセージはCircuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.という形です。 - 復旧。 ブレーカーを叩き続けないでください。再試行する前に少なくとも
$secondsUntilHalfOpenを待つか、操作を機能低下させてください。 ネットワーク呼び出しは試みられなかったため、これはリモートサービス自体が失敗した証拠ではありません。接続プールを保護するバックプレッシャーです。
SiemEmitterException
「SiemEmitterException」という見出しのセクション- 送出される条件。 SIEM イベントエミッターがレコードを永続化またはチェーンできない場合。
ファイルシステムレベルの失敗（
open、lock、seek、write、fflush、read）と、ハッシュチェーンの完全性障害（chain: 順序外のインデックス、不正な末尾レコード、または JSON ラウンドトリップのずれ）を表面化させます。これらはハッシュチェーンイベントログと JSON-lines ファイルエミッターのアダプターで共有されます。 - クラス。
NextPdfExceptionを継承し、getContext()をオーバーライドします。 - コンテキストキー。
operation（open、lock、seek、write、fflush、read、chainのいずれか）、path（対象のログパス）、detail（バイト数や期待値対実際のインデックスなどの人間が読める詳細）。これらはgetOperation()、getPath()、getDetail()を通じても到達できます。メッセージはSIEM emitter <operation> failed for <path>: <detail>.という形です。 - 復旧。 これはアプリケーションロジックではなく、インフラストラクチャまたは SecOps が対処可能です。ログボリュームのマウント、ディレクトリ権限、
利用可能なファイルディスクリプター、ファイルシステムの健全性を確認してください。
chain操作の失敗は、監査ログの改ざんまたは破損のシグナルを示しており、 サイレントに再試行するのではなく調査すべきです。
レンダーマニフェスト
「レンダーマニフェスト」という見出しのセクションRenderManifestException
「RenderManifestException」という見出しのセクション- 送出される条件。 構造、型、またはスキーマ互換性のエラーにより、
RenderManifestを構築、デシリアライズ、または読み取りできない場合。マニフェストは、すべてのトランスポート（CLI、 Laravel queue、Symfony、SaaS API）が提出するバージョン管理された public コントラクトであるため、不正または非互換のマニフェストは、デフォルトに強制するのではなく直接表面化されます。 - クラス。
NextPdfExceptionを継承し、getContext()をオーバーライドします。名前付きコンストラクターは、SPEC-MANIFEST-*名前空間の安定した機械可読コードを設定します。RenderManifestException::shape()→SPEC-MANIFEST-001—RenderManifest::fromArray()中の shape または型エラー。RenderManifestException::incompatibleVersion()→SPEC-MANIFEST-002— 非互換のメジャースキーマバージョン（読み取り不可）。RenderManifestException::missingField()→SPEC-MANIFEST-003— ビルダーのファイナライズ中に必須フィールドが欠落。RenderManifestException::unsupported()→SPEC-MANIFEST-004— 整形式のマニフェストが、現在のレンダラーが解決できない入力またはテンプレートを参照（例: URI 入力やホスト限定のテンプレートエンジン）。
- コンテキストキー。
manifest_code（SPEC-MANIFEST-*識別子）とreason（人間が読める失敗の説明）。これらはgetManifestCode()とgetReason()を通じても到達できます。メッセージは[<code>] <reason>という形です。 - 復旧。
manifest_codeで分岐してください。SPEC-MANIFEST-001とSPEC-MANIFEST-003については、マニフェストのペイロードを修正してください（フィールドの型を修正するか、欠落しているフィールドを供給する）。SPEC-MANIFEST-002については、サポートされているメジャースキーマバージョンに対してマニフェストを再生成するか、レンダラーをアップグレードしてください。SPEC-MANIFEST-004については、現在のエディションが解決できる入力またはテンプレートエンジンを供給してください。
InspectException
「InspectException」という見出しのセクション- 送出される条件。 PDF 検査が失敗した場合。
- クラス。
RuntimeExceptionを直接継承します（NextPdfExceptionではない）。したがってgetContext()を保持しません。 - 保持するデータ。 2 つの public な
readonlyプロパティ。$inspectCode（INSPECT-*名前空間の機械可読コード）と$retryable（呼び出し側が再試行すべきかどうかを示すブール値。例えば検査サイドカーが一時的にダウンしている場合）。発生元の原因は、存在する場合、チェーンされた previous の throwable です。 - 復旧。 特定の失敗クラスについては
$inspectCodeで分岐してください。$retryableがtrueの場合は、失敗が一時的（サイドカーの再起動など）であると見込まれるため、バックオフを伴って再試行してください。falseの場合は、入力または構成を不具合として扱い、変更せずに再試行しないでください。
カオスエンジニアリング
「カオスエンジニアリング」という見出しのセクションChaosReportWriteException
「ChaosReportWriteException」という見出しのセクション- 送出される条件。
ChaosScenarioRunner::writeReport()が、集約されたカオスデイレポートをディスクに永続化できない場合。これは汎用のランタイムエラーのドメイン型置き換えであり、呼び出し側は、シナリオシミュレーター自体の内部で送出されるエラー（ランナーはそれらをChaosOutcomeフィールドとして捕捉する）と混同することなく、特定のレポートディスク失敗を捕捉できます。 - クラス。
NextPdfExceptionを継承し、getContext()をオーバーライドします。 - コンテキストキー。
output_path（ランナーが書き込もうとした絶対パス）。これはgetOutputPath()を通じても到達できます。メッセージはChaosScenarioRunner: failed to write report to "<path>".という形です。 - 復旧。 これはレポートシンクの書き込み側の失敗であり、シナリオの失敗ではありません。出力ディレクトリが存在し書き込み可能であること、そしてディスク容量が利用可能であることを確認してから、レポートの書き込みを再実行してください。カオスの結果自体は影響を受けません。
RetrievalUnavailableException
「RetrievalUnavailableException」という見出しのセクション- 送出される条件。 取得エンドポイント（例: Voyage Retrieval Augmented Generation サービス）が利用できず、システムがキャッシュのみのモードにフォールバックするか、フェイルクローズで動作する場合。
- クラス。
NextPdfExceptionを継承し、getContext()をオーバーライドします。 - コンテキストキー。
mode（失敗後の動作モード。結果がセマンティックキャッシュからのみ提供される場合はCACHED_ONLY、古いデータなしにリクエストが完全に拒否される場合はFAIL_CLOSED）とendpoint（到達不能になったエンドポイント）。これらはgetMode()とgetEndpoint()を通じても到達できます。メッセージはRetrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.という形です。 - 復旧。
modeを読み取って、システムがどのように機能低下したかを把握してください。CACHED_ONLYの下では、結果が古い可能性があります。エンドポイントが回復したら更新してください。FAIL_CLOSEDの下では、リクエストは設計どおり拒否されており、エンドポイントが到達可能になった後に再試行する必要があります。新鮮な取得に依存する前に、エンドポイントの接続性（ネットワーク、認証情報、サービスの健全性）を回復してください。