All errors from simse use a consistent format across the ACP protocol, the CLI, and the web API.
A simse error serializes to a small JSON object with exactly two fields:
{
"coreCode": "SESSION_NOT_FOUND",
"message": "Human-readable description of the error"
}| Field | Type | Description |
|---|---|---|
coreCode | string | Machine-readable error identifier |
message | string | Human-readable error description |
The coreCode field is what you should match against in error-handling code; message is meant for display. When a simse error is surfaced over a transport such as JSON-RPC, that transport may wrap the payload in its own envelope, but the simse-specific portion always carries just coreCode and message.
SESSION_NOT_FOUND
The specified session ID does not exist. The session may have been deleted, or the ID may be incorrect.
Resolution: List your saved sessions with the simse resume CLI subcommand. Conversation history may still be available in the library even if the session record is gone.
CONFIG_INVALID_FIELD
A configuration field holds a value that is not valid for that field.
Resolution: Check the named field in your configuration files and correct its value. simse reports the offending field in the error message.
CONFIG_MISSING_REQUIRED
A required configuration field is absent.
Resolution: Add the missing field to your configuration file. The error message names the field that is required.
CONFIG_VALIDATION_FAILED
Configuration was parsed but failed overall validation -- for example, fields that are individually valid but inconsistent with each other.
Resolution: Review the validation details in the error message and reconcile the conflicting settings.
Provider errors come from the ACP backend that powers simse's reasoning.
PROVIDER_TIMEOUT
A request to the provider exceeded the configured timeout.
Resolution: Increase the request timeout in your ACP configuration, or check whether the provider is under heavy load.
PROVIDER_UNAVAILABLE
The provider could not be reached. The connection was refused, timed out, or the service is down.
Resolution: Verify the provider endpoint in your configuration and confirm the backend service is running and reachable.
PROVIDER_AUTH_FAILED
The provider rejected the supplied API key or credentials.
Resolution: Update the API key in your backend configuration and reconnect.
PROVIDER_RATE_LIMITED
The provider is throttling requests. You have exceeded its rate limit.
Resolution: Wait before retrying. If this happens frequently, reduce request volume or review your provider plan limits.
PROVIDER_HTTP_ERROR
The provider returned an HTTP error response. The message field carries the status and any detail the provider supplied.
Resolution: Inspect the message for the provider-reported cause and address it accordingly.
MCP_CONNECTION_ERROR
simse could not establish or maintain a connection to an MCP tool server.
Resolution: Check that the server's command and args in mcp.json are correct and the executable is installed. Restart simse to reconnect.
MCP_TOOL_ERROR
An MCP tool was invoked but the server reported a tool-level failure.
Resolution: Inspect the error message for tool-specific detail. Check the MCP server's own logs if available.
MCP_RESOURCE_ERROR
An MCP resource could not be listed or read.
Resolution: Confirm the resource exists on the server and that the server is connected.
MCP_SERVER_ERROR
An MCP server returned a server-level error unrelated to a specific tool or resource.
Resolution: Check the MCP server's status and logs. Restart the server if it is unresponsive.
TOOL_NOT_FOUND
A tool was invoked by name but is not currently registered. The tool may have been removed, or the MCP server that provides it may have disconnected.
Resolution: Run /mcp to see connected servers and their registered tools. Restart the MCP server if the tool should be available.
TOOL_EXECUTION_FAILED
The tool ran but failed during execution. The message field contains the tool's error output.
Resolution: Inspect the error message for tool-specific details. Check tool logs if available.
TOOL_PERMISSION_DENIED
The permission system rejected the tool call. The configured permission mode or a glob rule denied the operation.
Resolution: Check the permission mode and rules in your configuration. Adjust the mode or add an allow rule for the tool and path pattern.
TOOL_TIMEOUT
A tool exceeded its configured execution timeout.
Resolution: Increase the timeout for the tool, or check whether the tool blocked waiting on input or an external resource.
TOOL_PARSE_ERROR
The tool's input arguments or its returned output could not be parsed.
Resolution: Check that tool arguments match the tool's input schema. If the tool produced the malformed output, inspect the tool itself.
LIBRARY_NOT_INITIALIZED
A library operation was attempted before the library finished initializing.
Resolution: Wait for simse to finish starting up before issuing library operations.
LIBRARY_NOT_FOUND
The requested entry does not exist in the library.
Resolution: Verify the entry ID. Use library_search to locate the correct entry.
LIBRARY_EMPTY_TEXT
An entry was submitted with no text content.
Resolution: Provide non-empty content when adding a library entry.
LIBRARY_INVALID_INPUT
A library operation received input that is not valid -- a malformed ID, an out-of-range parameter, or similar.
Resolution: Check the parameters of the library operation against the documented inputs.
LIBRARY_EMBEDDING_FAILED
simse could not generate an embedding for a library entry, so it cannot be indexed for semantic search.
Resolution: Retry the operation. If it persists, check that the embedding provider is configured and reachable.
LIBRARY_DUPLICATE_DETECTED
The entry being added duplicates content already in the library.
Resolution: This is usually informational -- the existing entry is kept. Skip the duplicate, or withdraw the prior entry first if you intend to replace it.
LOOP_DOOM_LOOP
simse detected repeated identical tool calls. After several consecutive identical calls (default 3), the loop is flagged to break the repetitive pattern.
Resolution: The model is stuck repeating itself. The injected warning usually breaks the loop. If it persists, end the session and start fresh.
LOOP_TURN_LIMIT
The agentic loop reached its maximum number of turns for a single prompt.
Resolution: Break the task into smaller prompts, or raise the turn limit in your configuration if the task legitimately needs more steps.
LOOP_ABORTED
The agentic loop was cancelled before completing -- typically by user interruption.
Resolution: No action needed if you cancelled intentionally. Re-issue the prompt to continue.
LOOP_COMPACTION_FAILED
simse could not compact the session to free context space.
Resolution: Retry the prompt. If compaction keeps failing, start a fresh session to reset the context.
TASK_NOT_FOUND
The referenced task ID does not exist.
Resolution: Verify the task ID. List current tasks to find the correct one.
TASK_LIMIT_REACHED
The maximum number of concurrent or queued tasks has been reached.
Resolution: Wait for in-flight tasks to finish, or cancel tasks that are no longer needed.
TASK_CIRCULAR_DEPENDENCY
Task dependencies form a cycle, so they cannot be ordered for execution.
Resolution: Review the task dependencies and remove the cycle.
TASK_INVALID_STATUS
An operation was attempted on a task whose current status does not permit it -- for example, completing a task that never started.
Resolution: Check the task's current status before performing the operation.
Resilience errors come from simse's retry and circuit-breaker machinery and usually accompany an underlying provider or tool failure.
RESILIENCE_CIRCUIT_OPEN -- A circuit breaker has opened after repeated failures and is short-circuiting further attempts. Wait for the breaker to reset, or address the underlying failure.RESILIENCE_TIMEOUT -- A guarded operation exceeded its time budget.RESILIENCE_RETRY_EXHAUSTED -- All retry attempts for an operation failed. The error message carries the last underlying failure.RESILIENCE_RETRY_ABORTED -- A retry sequence was cancelled before completing.For all of these, address the underlying provider or tool error reported alongside the resilience code.
Template and chain errors are mostly internal to advanced prompt-templating and multi-step chain features and rarely surface in normal use.
TEMPLATE_EMPTY (a template has no content), TEMPLATE_MISSING_VARIABLES (the template references variables that were not supplied), TEMPLATE_INVALID_VALUE (a supplied variable value is not valid for the template). Resolution: supply all referenced variables with valid values.CHAIN_EMPTY, CHAIN_INVALID_STEP, CHAIN_STEP_FAILED, CHAIN_EXECUTION_FAILED, CHAIN_NOT_FOUND, CHAIN_MCP_NOT_CONFIGURED (a chain step needs an MCP server that is not configured), and CHAIN_MCP_TOOL_ERROR (an MCP tool failed inside a chain step). Resolution: review the chain definition and ensure every step is valid and its dependencies (including any required MCP servers) are configured.IO_ERROR
An underlying input/output operation failed -- for example, a disk read or write, often caused by a full disk, missing file, or a permissions problem.
Resolution: Check available disk space and file permissions for the simse data directory.
OTHER_ERROR
An error that does not fall into any other category. The message field carries the detail.
Resolution: Read the message for the specific cause. If it is unclear, consult simse logs.