Error Codes

Pedelec rejects async methods and emits session errors as objects:

type PedelecError = {
  code: string;
  message: string;
  details?: unknown;
};

try {
  await session.sendText(text);
} catch (error) {
  const value = error as PedelecError;
  console.error(value.code, value.message, value.details);
}

The tables below document common codes from the SDK and current bridge/runtime. Provider adapters can return additional codes. Always include a fallback for unknown values.

Browser and Extension

Code	Meaning	Recommended response	Retry?
EXTENSION_UNAVAILABLE	SDK is outside a supported page context or cannot reach the Extension	Check browser profile, installation, supported origin, and client initialization	After fixing environment; create a fresh client/page
EXTENSION_DISCONNECTED	Existing Extension port closed	Disable active controls; check Extension; reload/recreate client state	Not on the same broken client
SDK_ORIGIN_UNAVAILABLE	The Extension cannot determine or forward the SDK caller origin	Use a supported HTTP(S) page origin; reload after correcting the page context	After fixing origin/context
INVALID_ORIGIN	Extension popup received a non-HTTP(S) origin	Use HTTPS, localhost, or 127.0.0.1 as supported	After changing origin
STORAGE_ERROR	Extension could not read/write approved origins	Check Extension health/storage; reinstall if persistent	A limited retry is reasonable

getApprovalStatus() converts EXTENSION_UNAVAILABLE and EXTENSION_DISCONNECTED into installed: false instead of throwing.

Origin approval

Code	Meaning	Recommended response	Retry?
CREATE_SESSION_NOT_APPROVED	Origin could not be verified or another origin is pending	Explain the conflict/origin issue	After the condition clears
APPROVAL_REJECTED	User rejected or closed approval	Return to connect-ready state	Only after explicit user action
APPROVAL_TIMEOUT	Approval was not completed in time	Tell user to keep popup open; offer connect again	Yes, user initiated
OPEN_POPUP_FAILED	Extension could not open its popup	Ask user to click the Extension icon manually	Yes after manual action
THREAD_ACCESS_DENIED	The requested SDK session is owned by another origin, or the caller origin is invalid/missing	Do not retry with the same cross-origin ID; return to the owning origin or create a new session	Only after using the owner origin

Native and Core transport

Code	Meaning	Recommended response	Retry?
NATIVE_HOST_UNAVAILABLE	Extension cannot connect to registered native host	Start/repair Desktop App installation and host registration	After repair
NATIVE_CONNECTION_CLOSED	Native Messaging connection closed	Restart Desktop App and verify host	Read-only operation may retry after recovery
CORE_RUNTIME_UNAVAILABLE	Native host cannot reach a valid Core runtime after any background launch attempt	Open Desktop manually or repair its installation/launch configuration	After Core is ready
IPC_UNAVAILABLE	Local Core IPC could not bind, connect, parse, or respond	Restart Desktop App; inspect local logs	After recovery
MESSAGE_TOO_LARGE	Local IPC message exceeded its size limit	Reduce prompt/tool/result payload	Only with smaller data
WORKSPACE_LIST_TOO_LARGE	A workspace file or folder listing cannot fit in the browser transport envelope	List a narrower workspace path	After reducing the result
WORKSPACE_RUN_OUTPUT_TOO_LARGE	Workspace script stdout/stderr cannot fit in the browser transport envelope	Reduce script output or capture it in a workspace file	After reducing the output
SDK_BRIDGE_TIMEOUT	Extension did not answer within bridgeTimeoutMs	Check all downstream layers; avoid repeated writes	After diagnosing connection
DIRECTORY_PICKER_FAILED	The native directory picker could not be created, shown, or converted to the SDK path result	Ask the user to retry and check Desktop/native dialog support; cancellation is not an error	Usually after the dialog/runtime issue is fixed
WORKSPACE_PATH_INVALID	The requested workspace path is not absolute, is not a directory, overlaps the managed workspace root, or cannot be resolved	Choose a valid application-managed workspace path	After fixing the path
WORKSPACE_CREATE_FAILED	Pedelec could not create or initialize a managed workspace or its private runtime data	Preserve the application-owned workspace and inspect the error details	After fixing the filesystem issue
WORKSPACE_REMOVE_FAILED	Pedelec could not remove a managed temporary workspace	Keep the path available for cleanup and inspect locked-file or permission details	After the filesystem issue clears
WORKSPACE_OPEN_FAILED	Desktop could not open the validated Workspace folder	Check the folder and OS opener integration	After fixing the opener issue
WORKSPACE_NOT_FOUND	The Workspace capability or its recorded directory no longer exists	Reopen the custom Workspace or create a new Session; do not reconstruct a handle from only a path	After the Workspace exists again
WORKSPACE_ACCESS_DENIED	The process cannot read, write, or initialize the requested Workspace path	Check OS permissions, ownership, locks, and the application’s access grant	After permissions are corrected
SDK_TRANSPORT_ERROR	Generic bridge request failure	Inspect message/details; verify Extension/native/Core	Depends on operation
SDK_PROTOCOL_ERROR	Response/event shape or request type did not match SDK expectations	Align component versions; report reproducible mismatch	Usually not until versions/config fixed

Workspace Runtime execution

Code	Meaning	Recommended response	Retry?
DENO_EXECUTION_TIMEOUT	Workspace TypeScript code exceeded its positive timeout, which defaults to 60 seconds	Increase the timeout only when appropriate, or split/shorten the script	Yes after changing the work
DENO_EXECUTION_CANCELLED	Workspace Runtime execution was cancelled during shutdown or interruption	Reconcile partial Workspace writes before retrying	After the Workspace/runtime is usable
DENO_RUNTIME_UNAVAILABLE	The managed Deno runtime cannot be located or started	Restart Desktop so it can prepare the runtime again. Reinstall Desktop if preparation keeps failing	After the runtime is available
DENO_PROCESS_SPAWN_FAILED	Desktop could not spawn the Deno process	Check Desktop installation, executable permissions, and runtime logs	After fixing the process environment
DENO_PROCESS_IO_FAILED	Deno process stdin/stdout/stderr communication failed	Treat the operation as failed, inspect runtime logs, and reconcile partial writes	After transport/runtime recovery
DENO_MODULE_NAME_INVALID	A logical Runtime Module name is not a supported bare or scoped package-like specifier	Use a valid module name such as scene-tools or @example/scene-tools	After fixing the declaration
DENO_MODULE_SETUP_INCOMPLETE	A requested Workspace or Session Runtime Module is not ready, or setup/upload for that same module identity is still pending	Finish or retry that module’s setup. Other Workspace activity does not block it	Yes after that module’s setup is complete
DENO_MODULE_NOT_FOUND	The requested module was not declared in the owning Workspace scope or Thread snapshot	Include the module in the explicit run/setup request or create a new Session snapshot	After correcting the request
DENO_MODULE_ALREADY_READY	A ready module package is immutable for the current Core runtime scope	Use the existing package or choose a new logical module name for a new implementation	Only with a new name
DENO_MODULE_ARTIFACT_TOO_LARGE	The prepared runtime/declaration envelope exceeds the 100 MiB upload limit	Reduce the bundled artifact or split the module	After reducing the artifact
DENO_MODULE_ARTIFACT_INVALID	The uploaded Runtime Module envelope or its runtime/declaration sources are invalid	Rebuild with the Vite plugin and retry	After rebuilding
DENO_MODULE_MATERIALIZATION_FAILED	Core could not safely commit or validate the private module package	Inspect filesystem/runtime health without exposing private paths to users	After fixing the filesystem/runtime issue
DENO_MODULE_UPLOAD_SERVER_UNAVAILABLE	The local bounded upload endpoint is unavailable	Restart or repair the Desktop/Core runtime	After the upload endpoint is ready
DENO_MODULE_UPLOAD_TICKET_EXPIRED	The short-lived module upload ticket expired	Request a fresh setup/upload ticket	Yes with a fresh ticket
DENO_MODULE_UPLOAD_UNAUTHORIZED	The upload ticket, token, owner, or module scope is invalid	Do not reuse the ticket; restart setup through the owning SDK origin	Only with a fresh authorized setup
DENO_MODULE_UPLOAD_SIZE_MISMATCH	Uploaded bytes differ from the ticketed envelope size	Retry with the exact prepared artifact body	Yes after correcting the body
DENO_MODULE_UPLOAD_FAILED	The module upload could not be transferred or committed	Inspect the cause, then retry the Workspace setup or recreate the Session	After recovery
DENO_MODULE_SETUP_FAILED	The module setup completed transport but did not produce a ready package	Rebuild/retry the setup; ready packages are not hot-swapped	Yes after correcting the setup

Provider and configuration

Code	Meaning	Recommended response	Retry?
DEFAULT_PROVIDER_NOT_SET	No Desktop default provider exists	Ask user to choose one or pass provider explicitly	After configuration
DEFAULT_PROVIDER_UNAVAILABLE	Configured default is currently unavailable	Choose/install another provider	After configuration
PROVIDER_SCAN_FAILED	The initial provider availability scan failed	Preserve the error details, inspect Desktop logs, and retry after recovery	After recovery
MODEL_REQUIRED	Profile-mode provider, notably Ollama, requires a model in the selected Desktop effort profile	Configure a profile model in Desktop Settings, or use explicit createSession({ model }) mode	After configuration
INVALID_INPUT	SDK input is invalid	Fix application code/input shape	Not unchanged
PROVIDER_PROMPT_TOO_LARGE	Provider prompt exceeds a provider-specific launch limit; currently Antigravity rejects prompts over 20,000 UTF-16 code units	Shorten the user message and, for a first turn, any injected Pedelec guidance/tool metadata that contributes to the constructed prompt	After reducing the prompt
OLLAMA_API_KEY_REQUIRED	Ollama agent received no usable API key	Set ollama for local Ollama or a valid remote/Cloud key in Desktop Settings	After configuration
OLLAMA_AUTH_FAILED	The configured endpoint rejected authentication	Correct the endpoint credentials	After configuration
OLLAMA_MODEL_NOT_FOUND	The selected Ollama model was not found	Install/select a valid model	After configuration
OLLAMA_CLOUD_LIMIT_EXCEEDED	Ollama Cloud limit was reached	Wait or change plan/endpoint	After service recovery
OLLAMA_BASE_URL_INVALID	Configured Ollama base URL is invalid	Correct the URL in Desktop Settings	After configuration
OLLAMA_UNAVAILABLE	Ollama endpoint cannot be reached	Start local Ollama or repair endpoint/network	After recovery
OLLAMA_REQUEST_FAILED	Ollama request failed for another endpoint reason	Preserve message; inspect endpoint and logs	Depends on cause
OLLAMA_RESPONSE_INVALID	Ollama endpoint returned an unusable response	Verify endpoint compatibility and report details	After endpoint fix

Tavily web search

These errors can surface from the bundled Ollama agent only when a Tavily API key enables its internal web_search tool.

Code	Meaning	Recommended response	Retry?
TAVILY_UNAVAILABLE	Web search could not initialize or reach Tavily	Check network/service availability	After recovery
TAVILY_REQUEST_INVALID	Tavily rejected the generated search request	Preserve details; report a reproducible query	Only after changing the request
TAVILY_AUTH_FAILED	Tavily rejected the configured API key	Correct the Tavily key in Desktop Settings	After configuration
TAVILY_RATE_LIMITED	Tavily temporarily rate-limited the request	Wait before retrying	Yes, later
TAVILY_USAGE_LIMIT_EXCEEDED	The Tavily account usage limit was reached	Wait for quota reset or change the account/plan	After quota recovery
TAVILY_REQUEST_FAILED	Tavily returned another request failure	Preserve message/details; inspect service status	Depends on cause
TAVILY_RESPONSE_INVALID	Tavily returned an unusable result shape	Report the response incompatibility	After service/runtime fix
TAVILY_MODEL_ROUND_LIMIT_EXCEEDED	The model attempted more than 10 searches in one model round	Let the agent continue without another search or start a later turn	In a later model round

Provider-specific errors can describe authentication, executable startup, model support, server connectivity, web search, or provider output parsing. Display the provider and preserve the original message.

Session and turn

Code	Meaning	Recommended response	Retry?
SESSION_BUSY	Session already has an active prepare/turn	Wait until idle; prevent duplicate submit	Yes after idle
SESSION_ENDED	Session can no longer accept work	Create or resume another valid session	Not on this handle
THREAD_NOT_FOUND	Core no longer has the requested session ID	Remove stale persistence or create another session	Not with the same missing ID
SESSION_ERROR	Runtime reported error state	Show failure; inspect provider/runtime detail	Usually create/recover deliberately
PREPARE_FAILED	SDK fallback code for failed preparation request	Continue normal send path if appropriate	Preparation can be retried deliberately
PREPARE_ACK_INVALID	Provider preparation output was not exactly PEDELEC_PREPARED after trimming	Keep the normal sendText() path available; preparation is an optimization	Yes after inspecting provider/runtime state
PREPARE_SESSION_ID_MISSING	Provider exited after preparation without a resumable session ID	Keep the normal sendText() path available; preparation is an optimization	Yes after provider recovery
SEND_TEXT_FAILED	SDK fallback code for failed send request	Preserve prompt; inspect transport/runtime	Only after state is known
END_SESSION_FAILED	End request failed; Core state is uncertain	Keep UI explicit; retry or verify runtime	Carefully
AUTO_END_SESSION_FAILED	Extension failed to end a disconnected auto-end session	Surface cleanup warning/log; verify Desktop	Carefully, often manual cleanup

Underlying structured errors are preserved when available, so fallback codes may be replaced by a more specific transport or runtime code.

Tools

Code	Meaning	Where it appears	Response
TOOL_HANDLER_NOT_FOUND	No named, inline, or generic handler matched	Error result sent to agent	Restore/register handler; fix name/lifecycle
TOOL_NOT_FOUND	Core ToolRegistry has no tool requested by the agent	Core/runtime error	Verify the tool manifest and agent request
TOOL_ARGS_INVALID	Agent arguments are not an object or do not match the tool schema	Core/runtime error	Correct the tool call/schema
TOOL_TIMEOUT	Core reached the App Tool’s formal timeout while waiting for a tool result	Core/runtime error	A received structured error means the invocation ended; reconcile possible side effects rather than treating it as an in-flight retry
TOOL_HANDLER_ERROR	Handler threw or rejected	Error result sent to agent	Log unexpected exception; return domain errors for expected cases
SUBMIT_TOOL_RESULT_FAILED	SDK could not deliver handler result	session.onError() SDK event	Reconcile side effects; inspect disconnect/timeout/serialization
WEBMCP_REGISTRATION_FAILED	document.modelContext.registerTool failed while binding App Tools	Rejected webmcp() promise	Fix the page registration failure. That call returns no binding and aborts tools registered earlier in the same call

A Core tool timeout can also lead to a session/runtime error or a later SUBMIT_TOOL_RESULT_FAILED. The browser handler is not forcibly cancelled.

Assets

Asset failures can occur while creating an SDK request, during loopback upload PUT or download GET, while listing assets, or while the SDK decodes UTF-8 and parses JSON. uploadAsset(), listAssets(), and readAsset() therefore surface errors from different stages.

Code	Meaning	Recommended response
ASSET_TOO_LARGE	File exceeds the 100 MiB limit	Choose a smaller file
ASSET_UPLOAD_SERVER_UNAVAILABLE	Desktop loopback upload server is unavailable	Check Desktop/Core availability and retry after recovery
ASSET_UPLOAD_TICKET_EXPIRED	Internal upload ticket expired	Start a fresh upload
ASSET_UPLOAD_UNAUTHORIZED	Upload ticket/token was rejected	Start a fresh upload; repair Desktop if persistent
ASSET_UPLOAD_SIZE_MISMATCH	Uploaded byte count did not match the selected file	Retry with the unchanged file; inspect a persistent failure
ASSET_UPLOAD_FAILED	Upload failed for another transport/runtime reason	Preserve details and retry only after diagnosis
ASSET_LIST_FAILED	Completed assets could not be listed	Retry a read after Desktop/session recovery
ASSET_PATH_INVALID	Path is outside the implicit assets/ root or contains unsafe segments	Use a valid /... path
ASSET_NOT_FOUND / ASSET_NOT_FILE	Requested asset is absent or not a regular file	Wait for the writer or choose a file path
ASSET_READ_TOO_LARGE	Read target exceeds 100 MiB	Choose a smaller asset
ASSET_DOWNLOAD_TICKET_EXPIRED / ASSET_DOWNLOAD_UNAUTHORIZED	Loopback download ticket was rejected	Start a fresh read
ASSET_READ_FAILED	Download or filesystem read failed	Retry after diagnosing the session/filesystem
ASSET_TEXT_DECODE_FAILED / ASSET_INVALID_JSON	SDK conversion could not decode UTF-8 or parse JSON	Use file or correct the file contents

Workspace files

workspace.uploadFile() and workspace.readFile() use Workspace path and file errors. They do not report THREAD_* or SESSION_* codes. Session asset methods keep the asset codes above.

Code	Meaning	Recommended response
WORKSPACE_FILE_TOO_LARGE / WORKSPACE_FILE_READ_TOO_LARGE	Upload or read exceeds 100 MiB	Choose a smaller file
WORKSPACE_FILE_TRANSFER_UNAVAILABLE	Local transfer server is unavailable	Check Desktop/Core and retry after recovery
WORKSPACE_FILE_UPLOAD_TICKET_EXPIRED / WORKSPACE_FILE_DOWNLOAD_TICKET_EXPIRED	One-time ticket expired	Start a fresh transfer
WORKSPACE_FILE_UPLOAD_UNAUTHORIZED / WORKSPACE_FILE_DOWNLOAD_UNAUTHORIZED	Ticket or token was rejected	Start a fresh transfer
WORKSPACE_FILE_UPLOAD_SIZE_MISMATCH	Uploaded byte count did not match the file	Retry with the unchanged file
WORKSPACE_FILE_UPLOAD_FAILED / WORKSPACE_FILE_READ_FAILED	Transfer or filesystem operation failed	Preserve details and retry after diagnosis
WORKSPACE_FILE_NOT_FOUND	Target file is absent	Check the Workspace-relative path
WORKSPACE_FILE_NOT_REGULAR	Target is a directory, symlink, junction, or other non-regular file	Choose a regular file
WORKSPACE_PATH_INVALID	Path is absolute, traverses with .., or otherwise is not a Workspace-relative path	Use a relative /-separated path without a leading slash
WORKSPACE_FILE_TEXT_DECODE_FAILED / WORKSPACE_FILE_INVALID_JSON	SDK could not decode UTF-8 or parse JSON	Use file or correct the contents

Runtime Full Access

Code	Meaning	Recovery
INVALID_INPUT	Session Full Access without Instance opt-in, invalid flag type, or both module fields	Correct the input
RUNTIME_FULL_ACCESS_NOT_APPROVED	Legacy SDK preflight error for incomplete Instance grants	Current SDK opens approval; Agent-only approval returns CREATE_SESSION_NOT_APPROVED
CREATE_SESSION_NOT_APPROVED	Extension rejects authorization or missing Native mode confirmation	Review permissions and update Extension/Desktop
SDK_PROTOCOL_ERROR	SDK did not receive runtimeFullAccessApplied: true	Update Extension/Desktop; never downgrade silently
RUNTIME_FULL_ACCESS_UNSUPPORTED	Native did not acknowledge revocation	Update Desktop; pending revocation remains queued

Existing DENO_* error code literals remain stable for the current engine and compatibility contract.