トラブルシューティング

August 7, 2026 · View on GitHub

最初に、メイン画面下部の状態表示と次のログを確認してください。

%LocalAppData%\LocalMCPChatClient\Logs\app-YYYYMMDD.log

ログには一般的な秘密値のマスク処理がありますが、共有前にパス、ツール引数、ツール結果へ秘密情報が含まれていないか確認してください。

アプリが起動しない

Portable ZIPの場合

  • ZIP内から直接実行せず、すべて展開してから起動する
  • 書き込み可能なフォルダーへ展開する
  • Windowsのプロパティに「ブロックの解除」が表示される場合は、配布元を確認した上で解除する
  • ZIPと同時に配布されたSHA-256とファイルハッシュを比較する
Get-FileHash .\LocalMCPChatClient-0.1.2-win-x64.zip -Algorithm SHA256

Visual Studioの場合

dotnet --version
dotnet restore LocalMCPChatClient.sln
dotnet build LocalMCPChatClient.sln -c Debug

.NET SDK version 10.0.300を選択できない場合は、.NET 10 SDKを導入するかdotnet --list-sdksでインストール状況を確認します。

モデルをダウンロードできない

  • モデル本体に加えて一時ファイル分の空き容量を確保する
  • プロキシ、VPN、ファイアウォールがHugging FaceまたはGitHubへの接続を妨げていないか確認する
  • Gemmaの配布ページで必要なライセンス条件を確認する
  • 中止後は同じ操作を再実行してRangeダウンロードを再開する
  • 手動取得したGGUFがある場合は「既存GGUFを登録」を使う

SHA-256不一致の場合は破損または配布物の変更が考えられます。不一致ファイルを使用せず、ダウンロードをやり直してください。

「モデルがインストールされていません」と表示される

「設定」→「モデルと推論」で次を確認します。

  1. 上部で選択したモデルがダウンロードまたは登録済みか
  2. モデル保存先または登録済みGGUFのパスが存在するか
  3. ファイルを外部ツールで移動・削除していないか

ファイルを移動した場合は「既存GGUFを登録」から再登録します。

llama-serverを起動できない

ランタイム未導入

「設定」→「モデルと推論」で使用するbackendを選び、「backendをダウンロード」を実行します。手元の実行ファイルを使う場合は「既存llama-serverを登録」を使用します。

GPUメモリ不足

  • コンテキスト長を下げる
  • E4BからE2Bへ変更する
  • 他のGPU使用アプリを終了する
  • 推論モードをCpuへ変更する

CudaまたはVulkanを明示選択した場合は、自動でCpuへフォールバックしません。Autoの場合だけCuda → Vulkan → Cpuの順で試行します。

モデル破損

「invalid gguf」「failed to load model」などがログにある場合は、モデルを再ダウンロードまたは再インポートします。

起動が90秒でタイムアウトする

CPU性能、ストレージ速度、モデルサイズによって初回読み込みが90秒を超える場合があります。E2Bまたは高速なストレージを試し、ログで読み込み進行とエラーを確認してください。

最初の応答や生成が遅い

  1. メイン画面の状態が「準備完了」になるまで待つ
  2. 推論モードをAutoにする
  3. 「設定」→「モデルと推論」→「速度診断を実行」でインストール済みバックエンドを比較する
  4. NVIDIA GPUでVulkanが選択されている場合は、CUDAランタイムを導入して診断結果を適用する

回答完了時の「初回 X.XX秒」は送信から最初の表示まで、「Y.Y tok/s」は生成速度です。初回だけ遅い場合はモデルのプリロード状態、毎回遅い場合は選択バックエンド、長い回答で画面だけカクつく場合は診断ログの生成速度と画面表示を切り分けて確認してください。

Gemmaが思考だけを生成して本文を表示しない場合、最新バージョンの標準システム指示が使われているか確認してください。本アプリは思考過程を非表示にするだけでなく、最終回答だけを生成するようモデルへ明示します。

起動時プリロードは初回応答を短縮する代わりに、アプリ起動中はモデルとKVキャッシュがRAMまたはVRAMを使用します。他のGPUアプリを優先する場合は「起動時にモデルを準備する」を無効にしてください。

MCPサーバーへ接続できない

Bearerトークン用の環境変数がない

エラーに表示された環境変数名と、設定画面の「Bearerトークンの環境変数名」を確認します。値を設定した後はLocalMCPChatClientを再起動してください。

URLまたはHTTPSエラー

  • ローカルHTTPはlocalhost、127.0.0.1などのループバックだけが許可される
  • リモートサーバーにはhttps://を使用する
  • URLにMCPエンドポイントのパス（例: /mcp）が含まれているか確認する

接続はできるが通知またはPOSTが失敗する

  • サーバーが通知用GETを実装しない場合は「standalone GET」を無効にする
  • サーバーがchunked requestを受け付けない場合は「Content-Lengthを送信」を有効にする
  • 必要なプロトコルバージョンヘッダーをNAME=VALUE形式で追加する

D3D12LookDevPTへ接続できない

  • D3D12LookDevPTの「MCP Server」パネルでサーバーが起動中か確認する
  • URLをhttp://127.0.0.1:8777/mcpにする
  • 「standalone GET」をオフにする。このサーバーのGET /mcpは仕様どおり405 Method Not Allowedを返す
  • MCP-Protocol-Versionを追加ヘッダーから削除し、SDKに2026-07-28を自動交渉させる
  • 401 Unauthorizedの場合は「Copy Token」でトークンを取り直し、環境変数または秘密のHTTPヘッダーを更新する
  • confirm_mutationsで変更処理が止まる場合は、サーバー側のMCPパネルで承認待ちをApproveまたはRejectする

画面付きの設定手順はD3D12LookDevPTとの連携例を参照してください。

stdioサーバーが起動しない

  • commandがPATHで解決できるか、または完全パスか確認する
  • 引数が1行に1つになっているか確認する
  • 作業ディレクトリが存在するか確認する
  • 必要な環境変数をプロファイルへ明示する

stdio起動ではシェルを使用しません。command欄にパイプ、リダイレクト、複数コマンドを記述してもシェル構文として解釈されません。

ツールが呼ばれない

  • 画面右上のMCP表示で接続数とツール数を確認する
  • 「設定」→「MCP接続」で接続テストを実行する
  • ユーザー入力で目的と必要な操作を具体的に伝える
  • そのツールがGemmaへ渡せるJSON Schemaを公開しているか確認する
  • 1ターン最大8回のツール反復へ達していないかログを確認する

モデルが必ずツールを選ぶ保証はありません。通常回答だけで完了した場合、ツールは実行されません。

設定を初期状態へ戻したい

通常は「設定」→「承認とプライバシー」→「すべての設定を初期化」を使用します。この操作はMCP接続を切断し、アプリが保存したCredential Managerの秘密情報と設定を初期化します。チャット履歴と取得済みモデル・ランタイムは保持されます。

設定画面を開けない場合だけ、次の手動手順を使用します。

  1. LocalMCPChatClientを終了する
  2. %LocalAppData%\LocalMCPChatClient\settings.jsonをsettings.backup.jsonなどへ名前変更する
  3. アプリを起動する

新しい既定設定が作られます。会話履歴を残す場合はhistory.dbを移動・削除しないでください。手動手順ではMCPの秘密値がWindows Credential Managerに残るため、不要になった資格情報はWindowsの「資格情報マネージャー」から確認してください。

問題報告に含める情報

  • Windowsのバージョン
  • アプリの入手方法（Portableまたはソースビルド）
  • 選択モデルと推論モード
  • CPU / GPUとドライバーバージョン
  • 再現手順
  • 状態表示と、秘密情報を除去した診断ログ

モデル本体、認証トークン、settings.json全体、非公開のツール結果は添付しないでください。