json-render 生成UIエラー時はどうする？2026 Reactトラブルシューティングガイド

json-render 生成UIエラーの本番対応では、モデルを再実行する前に「生成プロトコル、Schema検証、コンポーネント一覧、ストリーミング状態、業務権限」の順で故障層を切り分けます。安全に描画できない場合は、未登録のコンポーネントやアクションを実行せず、構造化テキストまたは固定UIへ降格する判断が適切です。

このガイドは、json-render のデモを実際のReactアプリへ移行しているフロントエンド開発者向けです。JSON Schema、コンポーネントの許可リスト、ストリーミングUIを保守するAIアプリ開発者や、クラウド上のエージェントにUIの生成・検証・公開を任せたいプラットフォームチームにも適しています。

最初に保存する診断情報

最終画面だけを見ていると、モデル出力の破損、変換処理の欠落、React側の例外を区別できません。1回の失敗を次の4つの記録として保存すると、LLM-to-UI排障が再実行可能な調査になります。

• 原始モデル出力。受信したJSON、JSONL、エラーメッセージを加工前の状態で保存します。
• 解析後のUI spec。パーサーがどのフィールドを削除・補完したかを記録します。
• レンダラーの結果。未知のコンポーネント名、propsの型不一致、イベント登録の失敗を含めます。
• 実行時情報。Reactのエラー、パッチ番号、接続状態、ユーザー権限、対象データ範囲を残します。

症状	最初に確認する層	代表的な原因	復旧方針
画面が完全に空白	解析とReactレンダリング	JSONの途中切れ、ルート要素欠落、例外の未捕捉	固定シェルを表示し、元入力を保持して再解析
一部だけ表示される	コンポーネント一覧とprops	未登録名、必須props欠落、バージョン差異	該当ノードだけ構造化テキストへ降格
Schema検証で停止する	生成契約	型違い、必須属性の欠落、ネストの切断	厳格検証後に修復または再生成
ボタンが反応しない	アクションと権限	イベント名の不一致、期限切れ状態、サーバー側拒否	操作を保留し、確認画面へ移行
内容が越権している	業務権限	モデルに権限判定を任せている、データ範囲未検証	サーバーで再認可し、応答を遮断

Schema契約の破損

json-render Schema校正失敗の対応では、まず「JSONとして読めるか」と「定義どおりのUI specか」を分けて判定します。JSON文字列として完全でも、必須属性の欠落や配列とオブジェクトの取り違えがあればレンダリング契約は成立しません。

JSON Schemaでは、オブジェクトの構造を properties、必須項目を required、許可しない追加項目を additionalProperties で表現できます。これらの役割はJSON Schemaのオブジェクト検証仕様で確認できます。

json-render Schema校正失敗の切り分け

次の順で検証すると、モデルの再試行を必要以上に増やさずに済みます。

1. 受信した文字列をJSONパーサーへ渡し、閉じ括弧や引用符の欠落を確認します。
2. JSONとして読めた値をSchemaバリデーターへ渡します。
3. エラーのパスを保存し、どのノードのどの属性が不正かを特定します。
4. 型の補正、既定値の追加、不要フィールドの削除を限定的に実施します。
5. 補正後に同じSchemaを再検証し、通過しなければ再生成または固定テンプレートへ戻します。

対応は、厳格に拒否する方法、限定的に自動修復する方法、モデルへ再生成させる方法に分かれます。自動修復は表示上の不足を補うための処理であり、権限、外部呼び出し、危険なイベントを正当化する仕組みではありません。

注意：Schemaを通すために未知のフィールドを無条件で残したり、イベント属性を自動的に許可したりすると、表示エラーを隠したまま副作用だけを通す可能性があります。修復処理の後にも、コンポーネントとアクションの許可判定が必要です。

コンポーネント登録の境界

json-render コンポーネントが描画できない場合、Reactのコードそのものより先に、生成された名前と登録済みの名前を比較します。公式ドキュメントが示すように、JSON specをあらかじめ登録したコンポーネントへ対応付ける方式では、自由なコード生成ではなく、許可された描画部品の集合が安全性を左右します。コンポーネント登録とpropsの説明を基準に、フロントエンドの登録表を点検します。

確認対象	検証内容	失敗時の扱い
コンポーネント名	大文字・小文字、名前空間、別名の差	未知ノードとして隔離
props	型、必須項目、列挙値、長さの制限	Schemaエラーとして拒否
イベント	登録済みのアクション名か、入力形式が一致するか	操作を無効化して確認へ
バージョン	生成側の定義とReact側の登録表が同じか	互換変換または固定部品へ
危険属性	HTML挿入、外部URL、任意コードに相当する値がないか	値を削除し、描画を継続または降格

同名コンポーネントの衝突や段階的なバージョン更新も見落としやすい箇所です。登録表に識別子、対応バージョン、入力Schema、表示専用か操作可能かを持たせると、単なる「見つからないコンポーネント」より具体的に原因を追跡できます。

json-render コンポーネントが描画できないときに、モデルへReactコードを出力させて穴埋めする方法は避けるべきです。受け入れるのは登録済みのspecだけとし、未知ノードは構造化テキストへ変換するか、その部分だけを非表示にします。

JSONLストリーミングの整合性

LLM-to-UIのJSONLパッチ乱順は、接続の問題だけでなく、適用状態の設計不備でも起こります。json-renderのストリーミング方式では、途中まで届いたspecを即時表示できる一方、途中のUIを完成品として扱わない状態管理が必要です。公式のストリーミング仕様では、ストリームによるspec更新の考え方を確認できます。

障害	検証する値	実装上の防止策
パッチの乱順	連番、親パス、生成セッション	期待する番号以外を保留
同じ更新の重複	パッチID、受信時刻、適用履歴	冪等キーで二重適用を防止
接続の中断	終端イベント、再接続回数、最後の適用番号	不完全状態を操作不能にする
パスの不一致	対象ノードが現在のspecに存在するか	差分を破棄して全体を再取得
途中状態での操作	specの検証完了フラグ	最終検証までアクションを無効化

HTTPストリームを利用する場合、イベントの形式や再接続の扱いはMDNのServer-sent events解説と照合します。差分表現をJSON Patchに寄せる設計では、add、remove、replace、move、copy、testという6種類の操作を定義するRFC 6902との違いも確認します。

権限と副作用の分離

合法なJSON specでも、表示してよいことと実行してよいことは別です。カード、見出し、表などの表示部品、入力部品、データを書き換えるアクション、外部サービスを呼び出すアクションを別の権限グループに分けます。

モデルが「削除」や「公開」を含むspecを生成しても、サーバー側では次の値を再確認します。

• ユーザーが対象操作を実行できるか。
• 対象データがユーザーの所属範囲に含まれるか。
• アクション引数がSchemaと業務ルールの両方を満たすか。
• リクエストの再送によって同じ副作用が重複しないか。
• 確認画面や監査ログが必要な操作ではないか。

認可の判定をクライアントだけに置かない方針は、OWASPのAuthorization Cheat Sheetにも沿っています。UI上でボタンを隠すだけでは権限管理にならず、サーバーのエンドポイントで再認可しなければなりません。

条件分岐による安全な降格

自動修復を続けるか、固定UIへ戻すかは、故障の種類と副作用の有無で決めます。

• Schemaが不正で、表示専用のノードだけなら、限定的な補正後に再検証します。再検証に失敗した場合は固定テンプレートへ戻します。
• 未知のコンポーネントが含まれるなら、そのノードを構造化テキストへ変換します。未知のイベントは実行せず、登録作業を別の変更として扱います。
• JSONLが途中で切れたなら、未完成specを操作可能にせず、最後の安定版を表示して再取得します。
• 操作が書き込みや外部呼び出しを伴うなら、合法なJSONでも確認状態へ移します。サーバー側の再認可に失敗した場合は実行しません。
• 同じ入力で連続して失敗するなら、元の入力、出力、エラー、権限情報を保持し、人手による修正または再試行へ回します。

この分岐では「表示できるか」より「安全に意味を保てるか」を優先します。構造化テキストへの降格で情報を残せるなら空白画面より有用ですが、操作の意味まで推測して補うべきではありません。

回帰テストと排障記録

排障を完了したら、修正内容だけでなく、同じ故障が再発したときの判定条件をテストにします。最低限、正常なspec、必須項目の欠落、未知コンポーネント、propsの型違い、JSONLの重複、JSONLの中断、権限外アクション、再送による二重実行を用意します。

記録項目	保存する内容	回帰テストへの利用
原始出力	モデルから届いたJSONまたはJSONL	同じ入力の再現
解析結果	正規化後のUI spec	補正処理の検証
描画エラー	コンポーネント名、パス、例外	登録表とSchemaの監視
状態情報	パッチ番号、接続、完了フラグ	中断と乱順の再現
権限情報	操作者、対象範囲、アクション	認可境界の確認
降格結果	固定UI、構造化テキスト、確認画面	安全な復旧の保証

クラウド上のビルド環境や自動化エージェントで検証する場合も、生成結果だけでなく、失敗時に残ったspecとログを取得できる構成にします。環境の分離や運用手順を確認したい場合は、Zutcloudのヘルプセンターを参照し、要件が個別に分かれる場合はZutcloudへの相談窓口から確認できます。

実装前の確認リスト

• [ ] 原始モデル出力、解析後spec、Reactエラーを同じ相関IDで保存している
• [ ] JSON構文の検証とJSON Schemaの検証を分離している
• [ ] required、型、列挙値、追加プロパティを検査している
• [ ] 登録済みコンポーネント以外を描画しない
• [ ] propsとイベント名をコンポーネントの登録表と照合している
• [ ] JSONLパッチの順序、重複、適用済み状態を管理している
• [ ] 不完全specでは書き込みや外部呼び出しを無効にしている
• [ ] 表示、入力、書き込み、外部呼び出しを別権限として扱っている
• [ ] サーバー側でユーザー権限、データ範囲、引数を再確認している
• [ ] 固定UI、構造化テキスト、確認画面への降格をテストしている
• [ ] 「原始出力—解析結果—描画エラー—降格動作」を回帰ケースとして保存している

既存のローカル開発環境だけでこの検証を続けると、依存関係の差、ビルド資源の不足、チームごとの実行環境の違いが原因調査に混ざりやすくなります。汎用クラウド環境も、接続切断時のログやブラウザ操作の再現、権限分離の確認に手間がかかる場合があります。

一時的なReact検証環境を複数人で共有したい場合や、クラウドエージェントに生成・テスト・ロールバックを実行させたい場合は、Mac環境をレンタルできるZutcloudの構成も比較対象になります。長期の固定負荷、専用の物理機器、常時接続が必須なら自前環境の方が適しますが、短期の再現テストや隔離されたビルド用途では、環境を用意して破棄しやすい運用の方が、json-renderの失敗を回帰可能な記録へ変換しやすくなります。