トラブルシューティング¶

このページでは、現在の実装に基づいて起こりやすい Koharu の問題を扱います。主な対象は、初回ダウンロード、ランタイム初期化、GPU フォールバック、headless / MCP アクセス、パイプライン段階の順序、ソースビルド周りです。

最初に切り分けること¶

トラブルシュートするときは、まずどの層が壊れているかを切り分けてください。

アプリ起動
ランタイムまたはモデルのダウンロード
GPU アクセラレーション
detect、OCR、inpaint、render などのページパイプライン段階
headless または MCP 接続
ソースビルドとローカル開発

ここが分かるだけで、かなり問題を狭められます。

初回起動で Koharu がきれいに起動しない¶

考えられる原因:

ランタイムライブラリのダウンロードまたは展開がまだ終わっていない
初回モデルダウンロードが進行中
app-data ディレクトリに対するローカル権限が不足している
GPU 初期化に失敗し、フォールバック中に問題が出ている

試すこと:

特に遅いディスクや回線では、最初の起動時はもう少し待つ
--download 付きで一度起動し、GUI を開かずにランタイム依存物を先に取得する
--cpu 付きで一度起動し、GPU 経路が原因かどうか確認する
--debug 付きで一度起動し、コンソールログを確認する

# macOS / Linux
koharu --download
koharu --cpu
koharu --debug

# Windows
koharu.exe --download
koharu.exe --cpu
koharu.exe --debug

--cpu では動き、通常起動では動かない場合、問題は一般的な起動経路ではなく GPU 経路にあることが多いです。

モデルやランタイムのダウンロードに失敗する¶

Koharu は初回利用時に、次のためのネットワークアクセスを必要とします。

llama.cpp のランタイムパッケージ
必要に応じた GPU ランタイム支援ファイル
既定の vision / OCR モデル群
後から選ぶオプションのローカル翻訳モデル

起こりやすい原因:

一時的なネットワーク障害
GitHub release asset やモデルホスティングへのアクセス遮断
app-data ディレクトリに対するローカルファイル権限の問題

確認すること:

そのマシンから GitHub と Hugging Face のダウンロード先に到達できるか
--download を再試行すると成功するか
別プロセスやセキュリティツールがローカルランタイムディレクトリ内のファイルをロックしていないか

失敗が続く場合は、まず別ネットワークで試してください。そうすると、マシン固有の問題か upstream への到達性の問題かを早く分けられます。

NVIDIA GPU があるのに CPU にフォールバックする¶

Koharu が CUDA 13.1 対応を確認できない場合、これは想定された挙動です。

現在のランタイム挙動は次の通りです。

NVIDIA ドライバを検出する
ドライバ互換性を問い合わせる
ドライバが CUDA 13.1 対応を報告した場合のみ CUDA を使う
それ以外は CPU にフォールバックする

試すこと:

NVIDIA ドライバを更新する
更新後に Koharu を再起動する
--debug で挙動を確認する

ドライバが古い、または CUDA チェックに失敗する場合、Koharu は中途半端な CUDA 構成より CPU を優先します。

OCR、inpainting、export で何かが足りないと言われる¶

これは単純にパイプライン順序の問題であることがよくあります。

現在の API と MCP 層でよくある例:

No segment mask available. Run detect first.
No rendered image found
No inpainted image found

多くの場合、必要な前段階の出力がまだ存在していないだけです。

順番は次を使ってください。

Detect
OCR
Inpaint
LLM Generate
Render
Export

rendered layer や inpainted layer がないせいで export が失敗しているなら、何度も export をやり直すのではなく、欠けている段階を先に実行してください。

ページの detection や OCR の品質が悪い¶

よくある原因:

低解像度の元画像
変則的なページ切り出し
強いスクリーントーンやノイズの多いスキャン
作画と重なった難しい縦書きテキスト
detection 後の配置が悪い、または重複したテキストブロック

試すこと:

可能なら、よりきれいなページ画像から始める
翻訳前に検出されたテキストブロックを確認する
明らかにおかしいブロックを直してから後工程に進む
構造修正後に後段階を再実行する

構造が壊れていると、OCR もレンダリングもブロック形状に依存するため、下流の品質も一緒に悪化しやすくなります。

headless モードは起動するが Web UI を開けない¶

まず基本を確認してください。

--headless を付けたか
固定ポートを指定したか
プロセスがまだ動いているか

例:

koharu --port 4000 --headless

その後、次を開きます。

http://localhost:4000

重要な実装上の点:

Koharu は 127.0.0.1 にバインドされます

つまり、ローカル Web UI は、自分でネットワーク公開しない限り同じマシンからしか見えません。

また、選んだポートを別プロセスがすでに使っていないかも確認してください。

MCP クライアントが接続できない¶

固定ポートを使い、クライアントは次に向けてください。

http://localhost:9999/mcp

よくある間違い:

/mcp ではなくルート URL を使う
--port を付け忘れる
Koharu プロセスがすでに終了したあとに接続しようとする
ポートを明示的に公開せず、別マシンから到達できると思う

通常の headless Web UI アクセスは動くのに MCP だけ動かない場合、まず URL のパスが正しいかを確認してください。サーバー障害より単純なパス間違いのほうが多いです。

Antigravity、Claude Desktop、Claude Code を使う場合は、MCP クライアントを設定するにあるクライアント別設定に従ってください。

読み込みしても何も起きないように見える¶

現在文書化されている読み込みフローは画像ベースです。Koharu が受け付けるのは次の形式です。

.png
.jpg
.jpeg
.webp

フォルダ読み込みでは、これらの拡張子だけに再帰的に絞り込みます。

フォルダを読み込んだのに空に見える場合は、そのフォルダに対応画像ではなく、アーカイブや PSD など別形式しか入っていない可能性を確認してください。

export が失敗する、または想定と違う出力になる¶

現在のパイプライン状態に合った出力形式を選んでください。

rendered export には rendered layer が必要
inpainted export には inpainted layer が必要
編集可能なテキストや補助レイヤーを残したいなら PSD export が最適

加えて、次も覚えておいてください。

rendered export には _koharu サフィックスが付く
inpainted export には _inpainted サフィックスが付く
PSD export は _koharu.psd を使う
従来 PSD export は 30000 x 30000 を超える画像を拒否する

極端に大きなページなら、PSD export を期待する前にリサイズまたは分割してください。

Windows でソースビルドに失敗する¶

Windows のビルドヘルパーは次を前提にしています。

既定の CUDA ビルド経路向け nvcc
Visual Studio C++ tools に含まれる cl.exe

Bun ラッパースクリプトは両方の自動検出を試みますが、どちらかが見つからないと Tauri が立ち上がる前に失敗することがあります。

プロジェクト推奨のラッパーコマンドを使ってください。

bun install
bun run build

Tauri コマンドを自分で制御したい場合は次を試します。

bun tauri build --release --no-bundle

より低レベルな Rust ビルドには次を使います。

bun cargo build --release -p koharu --features=cuda

まずアプリが動くかどうかだけ確認したいなら、CUDA ツールチェーン全体を追う前に CPU-only 起動を試すほうが早いことがあります。

手動で選んだ feature path が原因でソースビルドに失敗する¶

デスクトップビルドはプラットフォーム依存です。

Windows と Linux は cuda
Apple Silicon の macOS は metal

低レベルの cargo コマンドを手動で叩く場合、プラットフォームに合わない feature を指定すると、ビルド失敗や不整合なバイナリの原因になります。ソースからビルドするのプラットフォーム別例に従ってください。

ローカルでのデバッグを打ち切ってよいタイミング¶

次の状態なら、問題報告に十分な切り分けはできています。

--cpu では動くが GPU モードでは動かない
健全なネットワークでも --download が一貫して失敗する
同じページで毎回再現するパイプライン障害がある
headless モードは起動するのに、正しい localhost URL でも失敗する

この段階では、次を集めてください。

OS とハードウェア情報
実行した正確なコマンド
--cpu で結果が変わるか
正確なエラーメッセージ
その問題が特定の 1 ページだけか、すべてのページで起きるか

トラブルシューティング¶

最初に切り分けること¶

初回起動で Koharu がきれいに起動しない¶

モデルやランタイムのダウンロードに失敗する¶

NVIDIA GPU があるのに CPU にフォールバックする¶

OCR、inpainting、export で何かが足りないと言われる¶

ページの detection や OCR の品質が悪い¶

headless モードは起動するが Web UI を開けない¶

MCP クライアントが接続できない¶

読み込みしても何も起きないように見える¶

export が失敗する、または想定と違う出力になる¶

Windows でソースビルドに失敗する¶

手動で選んだ feature path が原因でソースビルドに失敗する¶

ローカルでのデバッグを打ち切ってよいタイミング¶

関連ページ¶