> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/ja/rissu/troubleshooting.md).

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

以下の各問題は、Squish CLI / MCP サーバーの実際の失敗モードです。該当する場合は実際のエラーテキストも併記しています。基本ルールとして、CLI は終了します `0` 成功時は終了し、 `1` 失敗時は stderr にメッセージを出して終了します。MCP 呼び出しでは、クラッシュではなくツールエラーとして同じメッセージが返ります。

## ffmpeg または ffprobe がインストールされていない

**症状** — 実行するたびに即座に失敗し（exit 1）、次のメッセージが出ます:

```
ffmpeg と ffprobe が必要です（Squish はこれらを使ってフレームをサンプリングします）。
  macOS:  brew install ffmpeg
  Ubuntu: sudo apt-get install ffmpeg
ローカルにインストールしたくないですか？ホスト版 API ならローカルツールなしで Squish できます。無料の日次枠があり、カード登録は不要です:
  https://getsquish.app/developers
```

**原因** — Squish はシステム上の外部コマンドを呼び出します `ffmpeg`/`ffprobe` また、両方を次のオプションで事前チェックします `-version` 動画に触れる前に確認します。どちらかが PATH に見つからない場合、実行途中で落ちるのではなく、即座に失敗します。

**対処** — ffmpeg をインストールし（`brew install ffmpeg` macOS では `sudo apt-get install ffmpeg` Ubuntu では）インストールし、agent/MCP クライアントが動作する環境が、それを含む PATH を継承していることを確認してください。ローカルにインストールできない場合は、 [ホスト型 API](/squish/ja/hajimeni/quickstart-api.md) が同じ処理をリモートで行います。

## Node 20 未満

**症状** — `npm`/`npx` 次の警告を表示します `EBADENGINE` を取得する際に「Unsupported engine」警告を表示し `@getsquish/squish`、CLI が実行時に失敗することがあります。

**原因** — パッケージは次を宣言しています `"engines": { "node": ">=20" }`。古い Node バージョンはサポートされていません。

**対処** — Node 20 以上にアップグレードしてください（`node --version` で確認できます）。

## MCP サーバーがクライアントに表示されない

**症状** — その `squish_video` 設定を追加しても、ツールが Claude Code、Claude Desktop、Cursor、または他の MCP クライアントに表示されません。

**原因と対処** （確認する順序）:

1. **設定の typo、または誤ったファイル** — ブロックは次の下にある必要があります `mcpServers`、そして `"command": "npx"` と `"args": ["-y", "@getsquish/squish", "mcp"]`を、クライアントが実際に読み込む設定ファイルに記述します。次と照らし合わせてください。 [MCP クイックスタート](/squish/ja/hajimeni/quickstart-mcp.md).
2. **クライアントを再起動していない** — ほとんどのクライアントは起動時に MCP 設定を読み込みます。設定を変更したらクライアントを再起動してください。
3. **初回実行時のダウンロード遅延** — 初回の `npx -y @getsquish/squish` では npm からパッケージをダウンロードしますが、クライアントのサーバー起動待ち時間を超えることがあります。まずはターミナルから一度キャッシュを温めてください: `npx -y @getsquish/squish mcp` は起動して stdio で待機するはずです（停止するには Ctrl-C）。そのコマンドがターミナルで失敗する場合は、まずそのエラーを修正してください。クライアントが起動するのも同じプロセスです。

## 使用エラー（不正なフラグまたは入力）

**症状** — CLI は exit 1 で終了し、具体的な問題と usage 行を stderr に出力します:

```
usage: squish <video> [--density 3x3|4x4|5x5|6x6] [--start <t>] [--end <t>] [--out <dir>] [--json]
       squish mcp                 MCP サーバーを起動します（stdio）
       <t> = 秒（90）またはシート上に記載されたタイムコード（1:30、1:07.3）
```

**原因** — 実際のメッセージと、それぞれの発生条件です:

| エラー                                              | トリガー                                                                        |
| ------------------------------------------------ | --------------------------------------------------------------------------- |
| `不明なフラグ: <flag>`                                 | CLI に存在しないフラグです。usage 行と照らして綴りを確認してください。                                    |
| `<video> 入力がありません`                               | 動画パスが指定されていません。                                                             |
| `1 回の実行につき動画は 1 つです — 2 つ目の入力を受け取りました: <arg>`    | 位置引数が 2 つあります。CLI は 1 回の実行で動画を 1 つだけ受け取ります。スペースを含むパスをクォートしていない場合も、これが発生します。 |
| `--density は 3x3\|4x4\|5x5\|6x6 のいずれかである必要があります` | サポートされている 4 つのグリッド以外の density です。                                           |
| `--start には時刻が必要です — 秒（90）またはタイムコード（1:30）`       | `--start`/`--end` 値がない、または解析できない場合。                                         |
| `--out にはディレクトリが必要です`                            | `--out` に値がありません。                                                           |
| `squish mcp は引数を取りません`                           | 次の後に余分な引数があります `squish mcp` — このサブコマンドは引数を受け取りません。                          |

**対処** — フラグまたは値を修正してください。メッセージには何が間違っているかが正確に示されます。

## ウィンドウ指定エラー（`--start` / `--end`)

**症状** — ウィンドウ指定した実行は、次のいずれかで拒否されます（exit 1、stderr にメッセージ。同じ文面が MCP ツールエラーとして返ります）:

* `start (…) がクリップの終端 (…) と同じか、それ以降です` — `--start` クリップの終端を指しています、またはそれを過ぎています。
* `ウィンドウが空です — end (…) は start (…) より後でなければなりません` — `end` ≤ `start`。何も生成されず、実行はその場で拒否されます。
* `start は 0 以上の時刻でなければなりません` — start が負の値です。
* `ウィンドウが小さすぎて個別に扱えません: N セルが M ms に収まっています（エンジンはミリ秒精度でシークします — この density では最小値は約 K ms です）。ズームアウトするか、density を下げてください` — ウィンドウが次の幅より狭いです **1 セルあたり 2 ms** 到達可能な下限です（たとえば 3×3 の 9 セルなら 18 ms 未満、6×6 の 36 セルなら 72 ms 未満）。その下では隣接するセルのタイムスタンプが区別できなくなるため、エンジンはごまかさずに拒否します。

**エラーではありません** — `end` クリップの長さを超える指定は、終端に静かに切り詰められます（「5:00 からクリップの終わりまで」は自然なリクエストです）。ウィンドウ指定した `--json` 実行では、解決された境界が次に出力されます: `"window": { "start": …, "end": … }` そのため、実際に使われた値を確認できます。

**対処** — ウィンドウを広げる、density を下げる、またはメッセージで示された境界を修正してください。タイムコードは元動画に対する絶対値です。ズーム元のシートに記載されている値をそのまま渡してください。

## `<input> から再生時間を読み取れませんでした`

**症状** — 実行は事前チェックの直後に上記メッセージで失敗します。

**原因** — `ffprobe` 正の再生時間を抽出できませんでした。ファイルが動画ではない、破損している、またはローカルの ffmpeg ビルドがデコードできない形式です。

**対処** — ファイルがローカルで再生できることを確認してください。再生できる場合は、ffmpeg ビルドがそのコーデックをサポートしているか確認してください（`ffprobe <file>` で生のエラー内容が表示されます）、または MP4/H.264 のような一般的な形式に再エンコードしてください。

## 出力が見つかりません

**症状** — 実行は成功しました（exit 0）が、シートの場所を探しています。

**原因** — デフォルトでは、シートは **入力動画の横に保存されます** として `<basename>.sheet-N.jpg` （たとえば `clip.mov` → `clip.sheet-1.jpg` 同じディレクトリ内）です。

**対処** — 次を指定してください `--out <dir>` （CLI）または `out_dir` （MCP）で保存先を選択します。 `--json`、 `files[]` 配列には書き出された各シートの絶対パスが列挙されます。推測するのではなく、こちらを解析してください。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/ja/rissu/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.