Skip to Content
OrbixDocs
Block SDK · Reference

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:

CodeWhen it is thrownTypical fix
BLOCK_VALIDATION_FAILEDdefineBlock 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_MANIFESTvalidateManifest (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_MISMATCHmanifest.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_VIOLATIONRemoteExtensionLoader 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_UNAVAILABLEA host-only bridge operation was invoked when no host service was registered.Guard host-specific calls or run inside Orbix / renderBlock.
LIFECYCLE_ERRORA block lifecycle hook (init / dispose) threw an unhandled error.Wrap custom setup/teardown logic in try / catch.
RENDER_CRASHCaught by BlockErrorBoundary when a block component throws during React render.Check the Block Studio console stack trace and guard undefined state fields.
REGISTRY_COLLISIONDuplicate registration conflict when strict collision mode is active.Ensure each distinct block has a unique manifest.id.
CIRCULAR_DEPENDENCYA cycle was detected between connected block graph ports.Break the port loop between upstream and downstream blocks.
STORAGE_QUOTA_EXCEEDEDBrowser 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.

src/handle-errors.ts
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.capabilitySourceMeaning
document:read, document:write, document:navigatecapabilityEngine.verifyDocumentMissing entry in capabilities.document.
workspace:read:all_pages, workspace:write:pages, etc.capabilityEngine.verifyWorkspaceMissing entry in capabilities.workspace.
database:read:<dbId>, database:write:<dbId>, database:createcapabilityEngine.verifyDatabaseTarget database ID not listed in capabilities.database.
storage:local, storage:persistent, storage:cache, storage:sessioncapabilityEngine.verifyStorageStorage backend missing from capabilities.storage (check whether declaring ['persistent'] dropped 'local').
ai:generate, ai:context:selection, ai:context:document, ai:visioncapabilityEngine.verifyAIMissing entry in capabilities.ai.
workers:compute, workers:wasmcapabilityEngine.verifyWorkerMissing entry in capabilities.workers.
clipboard:read, clipboard:writecapabilityEngine.verifyClipboardMissing entry in capabilities.clipboard.
network, network:domain:<host>, network:method:<METHOD>capabilityEngine.verifyNetwork / orbixEgressFirewallTarget domain or HTTP method not permitted.
network:ssrf, network:auth-endpoint, network:dlp, network:rateorbixEgressFirewall / hostFetchPrivate IP blocked, /api/auth* blocked, secret fingerprint detected, or > 8 concurrent HTML-frame fetches.

Other host and Studio errors

  • ReservedNamespaceError (code: 'RESERVED_NAMESPACE') — thrown by BlockPublishingService and MarketplaceRegistry when a third-party block attempts to publish or install an ID starting with com.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 as Button or StatCard from the root @orbixdocs/sdk instead of @orbixdocs/sdk/ui.
  • CAPABILITY_DENIED (HTML / polyglot RPC reply) — returned in the postMessage response payload { error: string, code: 'CAPABILITY_DENIED', capability: string } when an HTML/polyglot frame calls a host RPC method rejected by authorizeHostRpc.

On this page