# Known Errors

Use when a OpenChatCut tool call fails or returns an unexpected shape.

- Repository: https://github.com/0xsline/OpenChatCut (2832 stars)
- Category: Engineering
- License: AGPL-3.0
- Last updated: 2026-10-21
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add 0xsline/OpenChatCut --skill known-errors -g -a claude-code -y`
Codex: `npx skills add 0xsline/OpenChatCut --skill known-errors -g -a codex -y`
Cursor: `npx skills add 0xsline/OpenChatCut --skill known-errors -g -a cursor -y`
Gemini CLI: `npx skills add 0xsline/OpenChatCut --skill known-errors -g -a gemini-cli -y`

## Description

Use when a OpenChatCut tool call fails or returns an unexpected shape.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Known Errors

`edit_item` update raw shape:

- Wrong: `{ "id": "abc", "fromFrame": 30 }`
- Right: `{ "json": "{\"updates\":[{\"id\":\"abc\",\"fromFrame\":30}]}" }`
- Use this same `updates` shape for common moves, trims, and track changes.

`edit_item` add raw shape:

- The new item goes inside the `adds` array of the `json` transaction: `{ "json": "{\"adds\":[{...}]}" }`.
- Use `edit_item` for simple video placement, for example `{ "json": "{\"adds\":[{\"type\":\"video\",\"assetId\":\"...\",\"fromFrame\":0}]}" }`.

Timeline overlap:

- Error text: `Overlap: updated item at ... would overlap existing item at ... on this track.`
- Do not force the write or delete the conflicting item silently.
- Retry the `edit_item` transaction with an explicit available `trackId`, for example an update containing `"trackId":"V2"`, or ask the user which layer should win.

Workspace path restrictions:

- `push_asset` on the external MCP only accepts public http(s) URLs as `filePath`. It rejects local paths, workspace paths, and chat attachment paths.
- For motion-graphic assets, pass the JSX source via `create_motion_graphic_from_code({ code:"...", name, width, height, durationInFrames })`. `push_asset` no longer accepts an inline `code` argument.
- Copying local media into the workspace is not the fix for video/audio/image/GIF imports; use `asset-import` and `import_media` instead.
- Use `import_media action=create_session`, then run the OpenChatCut media import helper once with the returned token for client-held files.

Browser video conversion failure:

The rest: https://github.com/0xsline/OpenChatCut/blob/HEAD/src/agent/skills/known-errors/SKILL.md