- name
- known-errors
- description
- Use when a OpenChatCut tool call fails or returns an unexpected shape.
Known Errors
edit_item update raw shape:
- Wrong:
{ "id": "abc", "fromFrame": 30 } - Right:
{ "json": "{\"updates\":[{\"id\":\"abc\",\"fromFrame\":30}]}" } - Use this same
updatesshape for common moves, trims, and track changes.
edit_item add raw shape:
- The new item goes inside the
addsarray of thejsontransaction:{ "json": "{\"adds\":[{...}]}" }. - Use
edit_itemfor 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_itemtransaction with an explicit availabletrackId, for example an update containing"trackId":"V2", or ask the user which layer should win.
Workspace path restrictions:
push_asseton the external MCP only accepts public http(s) URLs asfilePath. 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_assetno longer accepts an inlinecodeargument. - Copying local media into the workspace is not the fix for video/audio/image/GIF imports; use
asset-importandimport_mediainstead. - 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:
- Error text often includes
Unable to convert video without dropping audio/video tracksorunknown_source_codec. - Rerun the OpenChatCut media import helper; it owns frontend-aligned conversion and will surface a user-actionable error if conversion is impossible.
- Do not ask the user to re-import the same file through the editor UI as a workaround — the conversion path is the same, the error will repeat. Fix the source (re-encode locally with
ffmpeg) or pick a different file. - After the replacement asset is uploaded/transcribed, delete the failed original asset if it is unused. The clean final media pool should look like a successful import, not a failed import plus a replacement.