> 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/th/resources/troubleshooting.md).

# การแก้ปัญหา

ปัญหาทุกข้อด้านล่างเป็นโหมดล้มเหลวจริงของ Squish CLI / MCP server พร้อมข้อความ error จริงในกรณีที่มีอยู่ กฎทั่วไปคือ CLI จะจบการทำงาน `0` เมื่อสำเร็จ และ `1` เมื่อเกิดข้อผิดพลาดจะส่งข้อความไปที่ stderr; การเรียก MCP จะแสดงข้อความเดียวกันในรูป error ของเครื่องมือ ไม่ใช่การแครช

## ไม่ได้ติดตั้ง 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) และตรวจสอบว่า environment ที่เอเจนต์/MCP client ของคุณรันอยู่สืบทอด PATH ที่มีมันอยู่ หากคุณติดตั้งในเครื่องไม่ได้, the [hosted API](/squish/th/getting-started/quickstart-api.md) บริการบนระบบก็ทำงานเดียวกันได้จากระยะไกล

## Node เก่ากว่า 20

**อาการ** — `npm`/`npx` จะแสดง `EBADENGINE` คำเตือน "Unsupported engine" เมื่อดึง `@getsquish/squish`และ CLI อาจล้มเหลวตอนรันจริง

**สาเหตุ** — แพ็กเกจระบุว่า `"engines": { "node": ">=20" }`; Node เวอร์ชันเก่าไม่รองรับ

**วิธีแก้** — อัปเกรดเป็น Node 20 หรือใหม่กว่า (`node --version` เพื่อตรวจสอบ)

## MCP server ไม่ปรากฏในไคลเอนต์

**อาการ** — `squish_video` เครื่องมือไม่แสดงใน Claude Code, Claude Desktop, Cursor หรือ MCP client อื่น หลังเพิ่ม config แล้ว

**สาเหตุและวิธีแก้** (ตามลำดับที่ควรตรวจ):

1. **พิมพ์ config ผิดหรือใช้ไฟล์ผิด** — บล็อกนั้นต้องอยู่ใต้ `mcpServers`, พร้อม `"command": "npx"` และ `"args": ["-y", "@getsquish/squish", "mcp"]`, ในไฟล์ config ที่ไคลเอนต์ของคุณอ่านจริง ๆ เทียบกับ [เริ่มใช้งาน MCP](/squish/th/getting-started/quickstart-mcp.md).
2. **ยังไม่ได้รีสตาร์ทไคลเอนต์** — ไคลเอนต์ส่วนใหญ่อ่าน MCP config ตอนเริ่มทำงาน; ให้รีสตาร์ทไคลเอนต์หลังเปลี่ยน config ทุกครั้ง
3. **ความล่าช้าในการดาวน์โหลดครั้งแรก** — คำสั่งแรก `npx -y @getsquish/squish` จะดาวน์โหลดแพ็กเกจจาก npm ซึ่งอาจใช้เวลานานเกินที่ไคลเอนต์จะรอให้เซิร์ฟเวอร์เริ่มทำงานได้ ให้เติมแคชไว้ครั้งหนึ่งจากเทอร์มินัล: `npx -y @getsquish/squish mcp` ควรเริ่มทำงานและค้างรอที่ stdio (กด Ctrl-C เพื่อหยุด) ถ้าคำสั่งนั้นล้มเหลวในเทอร์มินัล ให้แก้ error นั้นก่อน — เพราะเป็นโปรเซสเดียวกับที่ไคลเอนต์จะเรียก

## ข้อผิดพลาดในการใช้งาน (แฟลกหรือข้อมูลนำเข้าผิด)

**อาการ** — CLI จะจบด้วย exit 1 และพิมพ์ปัญหาเฉพาะพร้อมบรรทัดการใช้งานไปที่ stderr:

```
usage: squish <video> [--density 3x3|4x4|5x5|6x6] [--start <t>] [--end <t>] [--out <dir>] [--json]
       squish mcp                 เริ่ม MCP server (stdio)
       <t> = วินาที (90) หรือ timecode ตามที่ระบุบนชีต (1:30, 1:07.3)
```

**สาเหตุ** — ข้อความจริงและสิ่งที่กระตุ้นแต่ละอัน:

| ข้อผิดพลาด                                                    | ตัวกระตุ้น                                                                                                                                   |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `ไม่รู้จักแฟลก: <flag>`                                       | แฟลกที่ CLI ไม่มี — ตรวจสะกดเทียบกับบรรทัดการใช้งาน                                                                                          |
| `ขาดอินพุต <video>`                                           | ไม่ได้ระบุพาธของวิดีโอ                                                                                                                       |
| `หนึ่งวิดีโอต่อการรันหนึ่งครั้ง — ได้อินพุตตัวที่สอง: <arg>`  | มีอาร์กิวเมนต์ตำแหน่ง 2 ตัว — CLI รับวิดีโอได้เพียงหนึ่งไฟล์ต่อครั้ง การไม่ใส่เครื่องหมายคำพูดกับพาธที่มีช่องว่างก็ทำให้เกิดแบบนี้ได้เช่นกัน |
| `--density ต้องเป็นค่าใดค่าหนึ่งใน 3x3\|4x4\|5x5\|6x6`        | ใช้ density นอกเหนือจากกริดที่รองรับทั้งสี่แบบ                                                                                               |
| `--start ต้องระบุเวลา — เป็นวินาที (90) หรือ timecode (1:30)` | `--start`/`--end` โดยมีค่าที่หายไปหรือแปลงไม่ได้                                                                                             |
| `--out ต้องระบุไดเรกทอรี`                                     | `--out` โดยไม่มีค่า                                                                                                                          |
| `squish mcp ไม่รับอาร์กิวเมนต์`                               | มีอาร์กิวเมนต์เกินมาหลัง `squish mcp` — ซับคำสั่งนี้ไม่รับเลย                                                                                |

**วิธีแก้** — แก้แฟลกหรือค่า; ข้อความจะบอกตรง ๆ ว่าผิดอะไร

## ข้อผิดพลาดเกี่ยวกับการกำหนดช่วงเวลา (`--start` / `--end`)

**อาการ** — การรันแบบกำหนดช่วงเวลาจะถูกปฏิเสธด้วยข้อความใดข้อความหนึ่งต่อไปนี้ (exit 1, ข้อความอยู่บน stderr; ข้อความเดียวกับ error ของเครื่องมือ MCP):

* `start (…) อยู่ที่/หลังจุดจบของคลิป (…)` — `--start` ชี้ไปที่หรือเลยท้ายคลิป
* `ช่วงว่างเปล่า — end (…) ต้องอยู่หลัง start (…)` — `end` ≤ `start` ไม่มีการสร้างอะไรออกมา; การรันถูกปฏิเสธทันที
* `start ต้องเป็นเวลาที่ ≥ 0` — start เป็นค่าติดลบ
* `หน้าต่างเล็กเกินไปจนแยกตำแหน่งได้ไม่ชัด: N ช่องครอบคลุม M มิลลิวินาที (เอ็นจินค้นหาด้วยความละเอียดระดับมิลลิวินาที — ค่าต่ำสุดประมาณ ≈ K มิลลิวินาทีที่ density นี้); ขยายช่วงให้กว้างขึ้นหรือ ลด density` — ช่วงแคบกว่า **2 ms ต่อช่อง** ขีดขั้นต่ำที่ระบุได้ (เช่น ต่ำกว่า 18 ms สำหรับ 9 ช่องของ 3×3, ต่ำกว่า 72 ms สำหรับ 36 ช่องของ 6×6) ต่ำกว่าค่าดังกล่าว ช่องที่ติดกันจะชนกันจนแยกไม่ออกว่าเป็น timecode ไหน ดังนั้นเอ็นจินจึงปฏิเสธแทนที่จะทำเหมือนว่าทำได้

**ไม่ใช่ข้อผิดพลาด** — `end` ช่วงที่เลยระยะเวลาของคลิปจะถูกหนีบไว้ที่ท้ายคลิปโดยไม่แจ้งเตือน ("from 5:00 to the end of the clip" เป็นคำขอที่สมเหตุสมผล) การรันแบบกำหนดช่วง `--json` จะสะท้อนขอบเขตที่แก้แล้วใน `"window": { "start": …, "end": … }` เพื่อให้เห็นว่าใช้ค่าอะไรจริง

**วิธีแก้** — ขยายช่วงเวลา ลด density หรือแก้ขอบเขตที่ข้อความระบุไว้ จำไว้ว่า timecode อ้างอิงแบบสัมบูรณ์จากวิดีโอต้นฉบับ: ส่งค่าตามที่พิมพ์ไว้บนชีตที่คุณกำลังซูมจากเป๊ะ ๆ

## `อ่านระยะเวลาจาก <input> ไม่ได้`

**อาการ** — การรันจะล้มเหลวทันทีหลังตรวจสอบเบื้องต้น พร้อมข้อความข้างต้น

**สาเหตุ** — `ffprobe` ดึงระยะเวลาเชิงบวกออกมาไม่ได้: ไฟล์ไม่ใช่วิดีโอ, เสียหาย, หรืออยู่ในฟอร์แมตที่ ffmpeg ที่ติดตั้งในเครื่องคุณถอดรหัสไม่ได้

**วิธีแก้** — ยืนยันว่าไฟล์เปิดเล่นได้ในเครื่อง; ถ้าได้ ให้ตรวจว่า ffmpeg build ของคุณรองรับ codec นั้นหรือไม่ (`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[]` อาร์เรย์จะระบุพาธแบบสัมบูรณ์ของทุกชีตที่เขียนออกมา — ให้ parse จากตรงนั้นแทนการเดา


---

# 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/th/resources/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.