Agents & MCP

Error codes

Every failure carries errors[].code. Nothing was committed (rolledBack: true).

2 min read

·

Kimo 1.0 · format 1.0

On this page1 section

Common validator issues inside SCHEMA_VIOLATION

Code	Cause	Fix
`DOCUMENT_NOT_OPEN`	Unknown or stale `docId` (the file was reloaded or closed)	Use `detail.currentDocId` if present, else `kimo_get_state` / `kimo_open`
`DOCUMENT_LOCKED`	Another process holds the file's write lease (`detail.holder`)	Use the holder (e.g. connect through the Kimo app), or open with `readOnly: true`
`LOAD_FAILED`	The file is not valid `.kimo` (left untouched)	Don't retry. Tell the user
`READ_ONLY`	Read-only open, newer format, library, or locked	Open writable, or edit the library file itself
`REVISION_CONFLICT`	`baseRevision` is behind (`detail.current`, `detail.changed`)	Re-query the changed nodes, rebuild the ops, retry with the new revision
`NODE_EXISTS`	An insert reused an existing id	Use `key`; Kimo mints ids
`NODE_NOT_FOUND`	An id or `@key` does not exist (`nodeId`, `path` = op index)	Check the id. A `@key` only works within the call that created it
`INVALID_PROPERTY`	A field is unknown for the node type or has a bad value	Compare with `schema` / `kimo://schema/1.0`
`INVALID_INPUT`	The tool input failed its schema (`path` points at it)	Fix the named field. Check spelling and types
`SCHEMA_VIOLATION`	The resulting document would be invalid (`detail` has the validator issue)	Apply `suggestion` (a one-line fix for unknown fields such as `unset`, `padding`, `fontSize`), else read the issue code (`VARIABLE_MISSING`, `INSTANCE_VISUAL_FIELD`, …) and change the op
`INSTANCE_STRUCTURE`	Tried to add/delete/move children inside an instance	Use `set_override` (`visible:false`, `slot`, `replace`), or `detach`
`BATCH_TOO_LARGE`	Over the `insert` limit (`detail.limit`: 40, 150 streamed)	One finished section (or sub-block) per call. `copy` is free
`CYCLE`	A move or instance would contain itself	Pick another parent or component
`OUT_OF_SCOPE`	Edit outside the node subtrees assigned to you	Stay inside your scope, or ask the coordinator
`PERMISSION_DENIED`	Policy level, allow-list, grant, or the user said no / didn't answer	Don't loop. Ask the user (Kimo › Settings › Agents), or take a non-destructive path
`ASSET_NOT_FOUND`	Image/font/file path missing	`kimo_assets {action:"import"}` first
`FILE_EXISTS`	`kimo_create` / `kimo_export` target exists	Choose another path, or `overwrite:true` for exports
`FILE_NOT_FOUND`	Path does not exist	Check the absolute path
`TIMEOUT`	Too slow, or the app restarted mid-call	Retryable: re-read, retry once
`RATE_LIMITED`	Too many calls too fast	Retryable after a short wait
`APP_NOT_RUNNING`	The relay cannot reach the Kimo app	Retryable: ask the user to start Kimo, or use `kimo mcp` (headless)
`PROTOCOL_MISMATCH`	Relay and app versions differ	Update Kimo or the CLI
`UNSUPPORTED`	Not available in this host (raster render without CanvasKit, headless SVG import, asset generation)	Use the alternative in `suggestion`
`INTERNAL`	Bug	Report it with the input. Re-read state before continuing

DOCUMENT_NOT_OPEN

Cause Unknown or stale docId (the file was reloaded or closed)

Fix Use detail.currentDocId if present, else kimo_get_state / kimo_open

DOCUMENT_LOCKED

Cause Another process holds the file's write lease (detail.holder)

Fix Use the holder (e.g. connect through the Kimo app), or open with readOnly: true

LOAD_FAILED

Cause The file is not valid .kimo (left untouched)

Fix Don't retry. Tell the user

READ_ONLY

Cause Read-only open, newer format, library, or locked

Fix Open writable, or edit the library file itself

REVISION_CONFLICT

Cause baseRevision is behind (detail.current, detail.changed)

Fix Re-query the changed nodes, rebuild the ops, retry with the new revision

NODE_EXISTS

Cause An insert reused an existing id

Fix Use key; Kimo mints ids

NODE_NOT_FOUND

Cause An id or @key does not exist (nodeId, path = op index)

Fix Check the id. A @key only works within the call that created it

INVALID_PROPERTY

Cause A field is unknown for the node type or has a bad value

Fix Compare with schema / kimo://schema/1.0

INVALID_INPUT

Cause The tool input failed its schema (path points at it)

Fix Fix the named field. Check spelling and types

SCHEMA_VIOLATION

Cause The resulting document would be invalid (detail has the validator issue)

Fix Apply suggestion (a one-line fix for unknown fields such as unset, padding, fontSize), else read the issue code (VARIABLE_MISSING, INSTANCE_VISUAL_FIELD, …) and change the op

INSTANCE_STRUCTURE

Cause Tried to add/delete/move children inside an instance

Fix Use set_override (visible:false, slot, replace), or detach

BATCH_TOO_LARGE

Cause Over the insert limit (detail.limit: 40, 150 streamed)

Fix One finished section (or sub-block) per call. copy is free

CYCLE

Cause A move or instance would contain itself

Fix Pick another parent or component

OUT_OF_SCOPE

Cause Edit outside the node subtrees assigned to you

Fix Stay inside your scope, or ask the coordinator

PERMISSION_DENIED

Cause Policy level, allow-list, grant, or the user said no / didn't answer

Fix Don't loop. Ask the user (Kimo › Settings › Agents), or take a non-destructive path

ASSET_NOT_FOUND

Cause Image/font/file path missing

Fix kimo_assets {action:"import"} first

FILE_EXISTS

Cause kimo_create / kimo_export target exists

Fix Choose another path, or overwrite:true for exports

FILE_NOT_FOUND

Cause Path does not exist

Fix Check the absolute path

TIMEOUT

Cause Too slow, or the app restarted mid-call

Fix Retryable: re-read, retry once

RATE_LIMITED

Cause Too many calls too fast

Fix Retryable after a short wait

APP_NOT_RUNNING

Cause The relay cannot reach the Kimo app

Fix Retryable: ask the user to start Kimo, or use kimo mcp (headless)

PROTOCOL_MISMATCH

Cause Relay and app versions differ

Fix Update Kimo or the CLI

UNSUPPORTED

Cause Not available in this host (raster render without CanvasKit, headless SVG import, asset generation)

Fix Use the alternative in suggestion

INTERNAL

Cause Bug

Fix Report it with the input. Re-read state before continuing

Common validator issues inside SCHEMA_VIOLATION

UNKNOWN_PROPERTY: suggestion names the Kimo field (padding → pad, fontSize → style.size, unset → the update op's own unset).
FEATURE_NOT_DECLARED: only from tools other than kimo_apply_ops (which declares features itself). Add the feature to the document or use the ungated form.
VARIABLE_MISSING / VARIABLE_TYPE: the binding names an unknown variable or one of the wrong type. Check kimo_get_variables.
INSTANCE_VISUAL_FIELD: a visual field on an instance's top level. Move it into props.
OVERRIDE_PATH_UNRESOLVED: the IdPath doesn't resolve (query with resolveInstances).
AT_WITHOUT_OVERRIDE: slot content without a slot override. Use set_override kind:"slot".
REF_NOT_COMPONENT: of names a node that isn't a component.