live2d-web ドキュメント

トラブルシューティング

読み込み、Cubism Core、描画、トラッキングで発生する問題を切り分けます。

まずエラーコードを確認する

Live2DError には、変わらないエラーコードと、問題が起きたファイルの URL、種類、 HTTP ステータスが含まれます。Issue にはこれらの値に加えて、ブラウザとモデルを書き出したバージョンを記載してください。ライセンス対象のファイルは添付しないでください。

原因: SSR・Node 環境や、DOM を利用できない Worker からブラウザ API を呼び出しています。確認: 呼び出し履歴の中から、最初の createLive2D() または DOM に依存する処理を探します。対処: コンポーネントのマウント後に呼び出し、 Next.js では Client Component から /react を読み込んでください。再試行: ブラウザで実行するように変更するまでは解決しません。

core-missing

原因: coreUrl で指定した Cubism Core を読み込めず、互換性のあるグローバルな Core も見つかりません。確認: スクリプトのリクエスト、CSP、CORS、Core 5.3 の URL を確認します。対処: 公式 Core を自分の環境で配信し、アクセス可能な URL を指定してください。再試行: パスまたはポリシーを修正したあとに可能です。

webgl-unsupported

原因: ブラウザが WebGL2 コンテキストを作成できません。確認: WebGL2 の対応状況、ハードウェアアクセラレーション、使用中のコンテキスト数を確認します。 対処: 対応するブラウザや GPU を使うか、不要な Canvas を破棄してください。 再試行: 実行環境が変わったあとにのみ有効です。

invalid-props

原因: API の引数やオプションが、文書で定めた形式または範囲から外れています。 確認: エラーメッセージに表示された項目を確認します。対処: 呼び出し時の値を修正してください。再試行: 同じ値のままでは解決しません。

invalid-tree

原因: React コンポーネントが必要な Provider の外にあるか、1つの Canvas に複数のモデルが接続されています。確認: Live2DCanvas と Live2DModel 周辺のコンポーネント構成を確認します。対処: Canvas 1つにつきモデルを1つだけ置き、 Hook は Provider の内側で使ってください。再試行: 構成を直すまでは解決しません。

lipsync-error

原因: 任意のリップシンク機能を準備または処理する途中で失敗しました。 確認: 安全な接続、マイク権限、AudioContext の状態、wLipSync のプロファイルを確認します。対処: ユーザーが画面を操作したタイミングで音声処理を再開するか、音量ドライバーを使用してください。再試行: 音声設定を直したあとに可能です。モデルの描画はそのまま続けられる場合があります。

tracking-error

原因: MediaPipe の初期化、推論、Worker との通信、または終了処理に失敗しました。 確認: 任意依存パッケージ、WASM・task のパス、CORS、CSP の worker-src、制限時間、ブラウザの対応状況を確認します。対処: ファイルや Worker の設定を直し、 Worker を利用できない環境では Main thread を選んでください。再試行: 原因を修正したあとにトラッカーを作り直します。

model-load-failed

原因: model3 または参照先のファイルで、HTTP エラー、CORS の拒否、ファイルの欠落、解析エラーが発生しています。確認: details.url、assetType、 httpStatus とブラウザの Network パネルを確認します。404 は主にパスの誤り、ステータスのないリクエスト失敗は CORS やネットワーク、解析エラーは破損または非対応のモデル形式が原因です。対処: ファイル名の大文字・小文字、参照パス、 MIME タイプ、CORS ヘッダーを直すか、モデルを再度書き出してください。 再試行: 一時的な通信障害の場合、またはファイルを修正したあとに可能です。

render-error

原因: 準備完了後に描画が停止しました。よくある原因は WebGL コンテキストの消失です。確認: コンソールに最初に表示されたエラーと、GPU コンテキストの数を確認します。対処: GPU の負荷を下げ、Canvas のエラー画面から再試行してください。 再試行: Stage の設定を保ったまま作り直せます。

adapter-error

原因: Backend が対応していない機能を要求したか、別の Backend が作成したハンドルを受け取りました。確認: Backend 名とオプションの対応表を確認します。 対処: 標準 Backend を使う、未対応のオプションを外す、または独自アダプターを更新してください。再試行: 設定を変えるまでは解決しません。

最小構成で再現する

原因が分からない場合は、機能を一度に外すのではなく、最小構成から順番に戻します。まず標準 Backend でモデル1体だけを表示し、そのあと motion、lip sync、tracking を1つずつ追加してください。

const character = await createLive2D({
  container: document.querySelector('#stage')!,
  coreUrl: '/live2dcubismcore.min.js',
  src: '/models/model.model3.json',
})
 
console.log(character.getModelInfo())
await character.playMotion('Idle', 0)

再現手順には、ブラウザと OS、最初に出たエラーコード、details、失敗した URL の HTTP status を記録します。ライセンスを確認できない Core やモデル本体は issue に添付しないでください。

安全に作り直す

一時的な通信障害や WebGL context loss から復旧するときは、古いインスタンスを解放してから新しく作成します。同じ container に複数の Canvas を残さないでください。

let character: Live2DInstance | undefined
 
async function reload() {
  character?.dispose()
  character = await createLive2D(options)
}
 
addEventListener('pagehide', () => character?.dispose(), { once: true })

tracking-error や lipsync-error の場合は、モデル全体ではなく該当する optional 機能だけを停止して再作成できます。原因が設定にあるエラーを無条件で繰り返し再試行しないでください。