Error codes
Error classes, OrbixErrorCode values, capability violation strings, and HTML frame RPC error responses.
Orbix uses distinct error classes for SDK contract/registration errors (OrbixSDKError) and runtime permission checks (SecurityCapabilityError). Check instanceof accordingly when handling errors in block code or tests.
OrbixSDKError
Thrown by defineBlock, validateManifest, blockStudioRegistry.register, LocalDevConnector, and RemoteExtensionLoader.
class OrbixSDKError extends Error {
readonly code: OrbixErrorCode;
readonly blockId?: string;
readonly field?: string;
readonly hint?: string;
readonly docsUrl?: string;
readonly details?: Record<string, any>;
readonly timestamp: number;
}Subclasses: BlockValidationError, BlockCapabilityError, BlockLifecycleError.
All OrbixErrorCode values
OrbixErrorCode defines exactly 10 string codes:
| Code | When it is thrown | Typical fix |
|---|---|---|
BLOCK_VALIDATION_FAILED | defineBlock called with undefined or without a component / render / Renderer function, or a property validator failed in BlockValidationError. | Pass a valid React component in defineBlock({ manifest, component }). |
INVALID_MANIFEST | validateManifest (or blockStudioRegistry.register with an empty id) found a missing id, reserved com.orbix.* prefix, invalid SemVer version, missing name/displayName, invalid surfaces, or invalid slashShortcut. | Inspect err.field and err.hint; see Manifest reference. |
SDK_VERSION_MISMATCH | manifest.sdk specifies a SemVer range that does not match the active host SDK_VERSION (3.0.0), such as ^2.0.0 or ^4.0.0. | Update "sdk" in manifest.json to "^3.0.0". |
CAPABILITY_VIOLATION | RemoteExtensionLoader rejected a non-loopback or untrusted extension URL, or BlockCapabilityError was constructed. | Load local dev modules only from loopback (localhost, 127.0.0.1, [::1]) or publish through Block Studio. |
HOST_UNAVAILABLE | A host-only bridge operation was invoked when no host service was registered. | Guard host-specific calls or run inside Orbix / renderBlock. |
LIFECYCLE_ERROR | A block lifecycle hook (init / dispose) threw an unhandled error. | Wrap custom setup/teardown logic in try / catch. |
RENDER_CRASH | Caught by BlockErrorBoundary when a block component throws during React render. | Check the Block Studio console stack trace and guard undefined state fields. |
REGISTRY_COLLISION | Duplicate registration conflict when strict collision mode is active. | Ensure each distinct block has a unique manifest.id. |
CIRCULAR_DEPENDENCY | A cycle was detected between connected block graph ports. | Break the port loop between upstream and downstream blocks. |
STORAGE_QUOTA_EXCEEDED | Browser localStorage or IndexedDB quota was exceeded on write. | Move large payloads from useStorage (localStorage) to usePersistentStorage (IndexedDB) or prune old entries. |
SecurityCapabilityError
Thrown by capabilityEngine.verify*, orbixEgressFirewall.checkEgress, and hostFetch when a block attempts an action outside its granted capabilities.
SecurityCapabilityError does not extend OrbixSDKError
SecurityCapabilityError extends standard Error directly and exposes err.capability (string) and err.details — it does not have an err.code property.
import {
OrbixSDKError,
SecurityCapabilityError,
} from '@orbixdocs/sdk';
export function describeBlockError(err: unknown): string {
if (err instanceof SecurityCapabilityError) {
return `Missing capability: ${err.capability}`;
}
if (err instanceof OrbixSDKError) {
return `SDK error [${err.code}] on field "${err.field ?? 'n/a'}": ${err.hint ?? err.message}`;
}
return err instanceof Error ? err.message : String(err);
}Common err.capability strings
err.capability | Source | Meaning |
|---|---|---|
document:read, document:write, document:navigate | capabilityEngine.verifyDocument | Missing entry in capabilities.document. |
workspace:read:all_pages, workspace:write:pages, etc. | capabilityEngine.verifyWorkspace | Missing entry in capabilities.workspace. |
database:read:<dbId>, database:write:<dbId>, database:create | capabilityEngine.verifyDatabase | Target database ID not listed in capabilities.database. |
storage:local, storage:persistent, storage:cache, storage:session | capabilityEngine.verifyStorage | Storage backend missing from capabilities.storage (check whether declaring ['persistent'] dropped 'local'). |
ai:generate, ai:context:selection, ai:context:document, ai:vision | capabilityEngine.verifyAI | Missing entry in capabilities.ai. |
workers:compute, workers:wasm | capabilityEngine.verifyWorker | Missing entry in capabilities.workers. |
clipboard:read, clipboard:write | capabilityEngine.verifyClipboard | Missing entry in capabilities.clipboard. |
network, network:domain:<host>, network:method:<METHOD> | capabilityEngine.verifyNetwork / orbixEgressFirewall | Target domain or HTTP method not permitted. |
network:ssrf, network:auth-endpoint, network:dlp, network:rate | orbixEgressFirewall / hostFetch | Private IP blocked, /api/auth* blocked, secret fingerprint detected, or > 8 concurrent HTML-frame fetches. |
Other host and Studio errors
ReservedNamespaceError(code: 'RESERVED_NAMESPACE') — thrown byBlockPublishingServiceandMarketplaceRegistrywhen a third-party block attempts to publish or install an ID starting withcom.orbix..UnknownSdkExportError— thrown when code imports a symbol from@orbixdocs/sdk(or a subpath) that does not exist on that entrypoint — for example importing UI components such asButtonorStatCardfrom the root@orbixdocs/sdkinstead of@orbixdocs/sdk/ui.CAPABILITY_DENIED(HTML / polyglot RPC reply) — returned in thepostMessageresponse payload{ error: string, code: 'CAPABILITY_DENIED', capability: string }when an HTML/polyglot frame calls a host RPC method rejected byauthorizeHostRpc.