{"id":84107,"plugin_id":"plugin_asdk_app_6adcdb5e71948191a00ad2b15d58ed1e","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-06T07:28:27.405Z","digest":"27c2a61885535a3ec15fe14a0507d51ba89d662fce464badb7f549d60e430483","against":null,"payload":{"description":"Troubleshoot rejected Aixcut calls by stable error code. Use for Tool failures. Do not use for ordinary editing.","included_files":[],"name":"aixcut-known-errors","skill_md_contents":"---\nname: aixcut-known-errors\ndescription: \"Troubleshoot rejected Aixcut calls by stable error code. Use for Tool failures. Do not use for ordinary editing.\"\n---\n\n# Aixcut Error Recovery\n\n## Conversation guidance\n\nExplain what failed, whether work may have partially completed, and the next recovery step. Continue safe recovery when the error contract allows it. If user action is required, name it and state what to retry or inspect afterward. Never present an uncertain state as a success or a definite failure.\n\nUse `error.code`, `error.type`, `error.retryable`, and `error.next_action` to choose recovery. Never branch on `error.message` text. A rejected response is not a successful edit.\n\n## `next_action` kinds\n\n| kind | Meaning |\n| --- | --- |\n| `none` | Recovery requires a user decision. |\n| `resolve_input` | Correct the input or ref before retrying. |\n| `retry` | Retry the same request after `after_seconds`. |\n| `poll` | Poll the same `job_id`. |\n| `receipt` | Confirm the original mutation with its original identity before dependent writes. |\n| `open_editor` | Open the required page first. |\n| `run_helper` | Run the specified local helper first. |\n| `wait_then_read` | The action was accepted but is still running. Wait `after_seconds`, then call the specified read endpoint. Do not report completion or resubmit the action. |\n\n## Input and contract errors\n\n- `MCP_ARGUMENTS_INVALID`, `MCP_ARGUMENT_UNKNOWN`: A field is missing, has the wrong type, or is not allowed. Send only fields declared by the selected Tool Schema.\n- `MCP_ACTION_INVALID`, `MCP_VIEW_INVALID`, `MCP_OPEN_TARGET_INVALID`: Use a supported action or view.\n- `MCP_IDEMPOTENCY_KEY_INVALID`: Generate a new UUID v4 for `idempotency_key`.\n- `MCP_ACTION_UNSUPPORTED`: Choose a Tool that supports the requested action.\n- `MCP_LAYOUT_CLIP_UNSUPPORTED`: The target has no visual content. Layout applies only to video and image clips, not audio or text.\n\n## Authorization and project context\n\n- `MCP_SCOPE_REQUIRED`: The current grant lacks a required scope. Let the Codex Host reauthorize; do not bypass the scope with another Tool.\n- `MCP_PROJECT_CONTEXT_REQUIRED`: No Project is active. Ask the user to select one or use `aixcut_open` to enter a Project.\n- `MCP_PROJECT_NOT_FOUND`, `MCP_PROJECT_NOT_INITIALIZED`: Confirm the target Project before continuing.\n\n## Mutation conflicts and uncertain state\n\n- `MCP_PLAN_REQUIRED`: This mutation is protected by the plan guard. Read the current Project and timeline, build a fresh `plan_context` for the intended action, and retry; do not reuse a stale revision or broaden `authorized_actions` beyond the user's request.\n- `MCP_PLAN_REVISION_STALE`: The Project changed after it was read. Confirm the original mutation receipt, reread the current timeline, and rebuild the plan; do not replay stale refs.\n- `MCP_PLAN_SCOPE_CONFLICT`: The plan's Project/Timeline, refs, preserve/delete lists, or declared deletions do not match the mutation. Reread and rebuild the exact scope; do not remove protections just to make the mutation pass.\n- `MCP_PLAN_ACTION_UNAUTHORIZED`: The action is outside `authorized_actions` or the mechanical plan's allowed operations. Do not broaden the plan; ask the user if the requested result requires additional scope.\n- `MCP_TRACK_LOCKED`: The target track is locked. Read its current state. If unlocking is part of the user's authorized request, call `aixcut_track(action=\"update\", locked=false)`, reread, then retry the intended clear/delete with a fresh `plan_context`.\n- `MCP_MUTATION_SERVER_REJECTED`: Read the latest snapshot and regenerate the operation. Do not replay the old payload unchanged.\n- `NLE_IDEMPOTENCY_CONFLICT`: The key is already bound to a different project, timeline, or action. Read the timeline and confirm whether the earlier write already achieved the intent before redoing. A same-key retry against the same target is reported as a replay instead, not as this error.\n- `MCP_TRACK_ENSURE_NOT_APPLIED`: Read-back found no track. Confirm the original receipt and current timeline before correcting anything; an absent projection alone does not authorize a new-key write.\n- `MCP_CANVAS_DEFAULTED`: This is a warning, not a failure. A `0×0` canvas was set to `1920×1080`. If portrait or another ratio is required, use `aixcut_project action=canvas` to override it.\n- `MCP_MUTATION_LOCAL_REJECTED`: Local validation failed, usually because a ref is stale or a range is out of bounds. Read fresh data and correct the input.\n- `MCP_PROJECTION_BARRIER_TIMEOUT`, `MCP_ZERO_QUERY_UNAVAILABLE`: The read did not finish before timeout. Retry the same read parameters.\n- `MCP_MUTATION_STATUS_UNKNOWN`: Preserve the original identity and query `aixcut_read(view=\"mutation_receipt\")`. Never treat a timeout or absent receipt as proof the write failed.\n\n## Browser and local media errors\n\n - `MCP_FRONTEND_NOT_BOUND`: This grant has never been bound to a browser client. Call `aixcut_open(target=\"project\", project_id=...)` once, immediately pass the complete `result.browser_handoff.url` to the official host browser-opening capability (Codex Desktop), then call `page_status`. Do not compose a plain Project URL.\n - `MCP_FRONTEND_CLIENT_OFFLINE`: This is not an OAuth failure; the current MCP grant has no active browser connection. Call `aixcut_frontend action=page_status` first. Continue only when `presence_connections >= 1` and the requested Project appears in `pages` (use `requested_project_id` and `online_pages` to distinguish another Project). If the target is absent and this turn has not performed the formal handoff, call `aixcut_open(target=\"project\", project_id=...)` once and immediately pass its complete handoff URL to the official host browser-opening capability (Codex Desktop). The host result `queued` only means the request is queued. After the handoff, check `page_status` once; if the target remains offline, ask the user to open or switch to it in the same MCP session. Retry the original page action at most once; never resubmit imports or loop through opens.\n- `MCP_FRONTEND_PAGE_NOT_ACTIVE`: The client is online, but the active page belongs to another Project or workspace. Use `details.online_pages` and `requested_project_id` to tell the user which Project to switch to.\n- `MCP_FRONTEND_CAPABILITY_UNAVAILABLE`: The page and Project are online, but the page has not reported support for this action. Wait 15–30 seconds and retry once; if still unavailable, report it.\n- `MCP_MEDIA_TYPE_MISMATCH`: The selected source is not compatible with the requested media operation. Read `aixcut_read view=sources` and choose a source whose media type matches the operation.\n- If the browser failure is unclear, call the read-only probe `aixcut_frontend action=page_status`. It returns `bound_frontend_client_id`, `binding_error`, `presence_connections`, `online_project_pages`, `online_studio_pages`, and `pages` without throwing an offline error. Use the result to decide whether the user must open a page, switch Projects, or wait.\n- Do not repeatedly resubmit the same request for any of the four browser states above. Do not loop through project opens while offline or use another Tool to pretend a page-only action succeeded.\n- `MCP_FRONTEND_TIMELINE_STALE`: The timeline changed. Read it again before capturing frames.\n- `MCP_FRONTEND_EXPORT_INVALID`, `MCP_EXPORT_INVALID_INPUT`: Page export parameters are invalid (format, dimensions, or frame rate). Correct the parameters and retry once; do not replay unchanged input.\n- `MCP_EXPORT_ALREADY_RUNNING`: Do not start another export. Check the existing run with `aixcut_frontend action=export_timeline_status`.\n- `MCP_EXPORT_FAILED`: Page rendering failed. Report `error_message`; do not replay unchanged input. If one corrected retry fails, stop and report it.\n- `MCP_EXPORT_CANCELLED`: The user cancelled the page export. Report cancellation; do not retry it as a failure.\n- `CAPTURE_PERMISSION_REQUIRED`: Browser permission for local media expired after a refresh or browser change. Ask the user to click anywhere in the Project page (or use its “Fix now” control), then retry the original request. Do not re-import the media or bypass the page.\n- `MCP_LOCAL_MEDIA_BRIDGE_UNREACHABLE`: The local media bridge URL is no longer serving the file. Do not retry the same URL. Either rerun the helper described by `aixcut-timeline-editing` to obtain its newly printed URL, or ask the user to upload through `prompt_add_material`. Never invent a URL.\n\nPage-export failures appear as `error_code` in `export_timeline_status`, not as a rejected Tool call. Follow `aixcut-export` for those results.\n\n## Server and rate-limit errors\n\n- `MCP_RATE_LIMITED`: Wait `retry_after_seconds`, then retry the same request.\n- `MCP_CLIPOS_UNAVAILABLE`, `MCP_CLIPOS_REQUEST_FAILED`, `MCP_INTERNAL_ERROR`: These indicate a server failure and may be retried. Stop and report after repeated failures.\n\n## Generation errors\n\n- `MCP_PROVIDER_TIMEOUT`, `MCP_PROVIDER_TASK_FAILED`: Report the Job's `error_code`. Do not submit a replacement job automatically.\n\n## Speech generation errors\n\nRead the current draft before correcting unavailable paragraph numbers or changed order. Refresh the speech catalog for unavailable voice identities. A rejected or changed quote needs a new accepted quote; an uncertain submit keeps its original frozen recovery and per-paragraph operation identities. Query known Jobs first and resume only the original recovery when needed; never regenerate successful children to repair an unknown sibling.\n\n## Transcript and source-analysis errors\n\n- `MCP_CAPTION_TRANSCRIPT_PENDING`: Voice audio exists or is on the timeline, but transcription is still running. Do not render voice again or fabricate captions. Reread the source later; run caption `regenerate` only when its status is `available`.\n- `MCP_CAPTION_TRANSCRIPT_EMPTY`: No usable transcript is available for caption regeneration. Do not retry unchanged or report that captions were rebuilt. Inspect the source transcript state; continue only after a transcript becomes available or ask the user for subtitle copy.\n- `MCP_SOURCE_TRANSCRIPT_MISSING`, `MCP_SOURCE_TRANSCRIPT_OUTDATED`, `MCP_SOURCE_TRANSCRIPT_EMPTY`: The source is already in the Project, but its transcript is missing, stale, or empty. Follow `transcript_status` in the error details; re-importing is not the remedy.\n- `MCP_SOURCE_WORD_TIME_LIMIT_INVALID`: A `source_lines` request for word-level timing has more than 50 rows. Lower `limit` or narrow the request with `selectors`.\n- `MCP_SOURCE_LINES_RESPONSE_TOO_LARGE`: A single transcript record exceeds the safe response size. Do not repeat the request. Continue any steps that can use text and timing, then report the oversized record.\n\n## User-facing reports\n\nWhen a call fails, state which Tool failed, the exact error code, and what the user needs to do next. Explain in the user's current conversation language. Never present a failed action as successful or claim a fix without read-back evidence.\n\n### Unknown mutation recovery\n\nFor `MCP_MUTATION_STATUS_UNKNOWN`, do not replay the payload or mint a new UUID. Preserve the returned `mutation_id`/`idempotency_key`, query `aixcut_read(view=\"mutation_receipt\")`, and follow its `next_action`. `pending`, `unknown`, and `not_found` remain unresolved; only the receipt's authoritative `applied`, `duplicate`, `noop`, or `rejected` status permits a dependent write. A same-identity retry is allowed only when the live contract explicitly returns that recovery action.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}