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
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 thread workspace folder	Check the folder and OS opener integration	After fixing the opener issue
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

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	Provider, notably Ollama, requires a model in the selected Desktop effort profile	Configure a model for the selected default, low, or high profile in Desktop Settings	After adding the model
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

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