Error Handling

CDF throws structured errors for bootstrap and configuration failures. Catch them to detect missing adaptors, duplicate registrations, invalid config, and provide meaningful feedback to users.

What it does

Instead of generic Error objects, CDF exports typed error classes with:

errorCode — machine-readable error identifier (e.g., ADAPTOR_NOT_FOUND)
context — additional details (missing adaptor name, expected values, etc.)
component — which CDF layer threw the error

This lets you handle specific failures in code, not just show generic error messages.

How to use it

Catch registry errors

Thrown during adaptor registration and bootstrap:

import { AdaptorRegistry, initCDF, ESPCDFRegistryError } from "@espressif/rainmaker-base-cdf";

const registry = AdaptorRegistry.getInstance();

try {
  registry.register(myAdaptor);
  registry.setActiveAdaptor(myAdaptor._identifier);
  await initCDF({ sdkAdaptorRegistry: registry });
} catch (e) {
  if (e instanceof ESPCDFRegistryError) {
    console.error(`Registry failed: ${e.errorCode}`);
    console.error("Details:", e.context);
    // Handle specific error codes...
    if (e.errorCode === "ADAPTOR_ALREADY_EXISTS") {
      // User registered the same adaptor twice
    }
  }
  throw e;
}

Catch config errors

Thrown when initCDF is called with missing or invalid config:

import { initCDF, ESPCDFConfigError } from "@espressif/rainmaker-base-cdf";

try {
  await initCDF({} as any); // Empty config!
} catch (e) {
  if (e instanceof ESPCDFConfigError) {
    if (e.errorCode === "CDF_CONFIG_MISSING") {
      console.error("Please pass a registry:", e.context);
      // Show setup instructions to user
    }
  }
}

Error types

Error class hierarchy

Class	Purpose
`ESPCDFError`	Abstract base class — has `component`, `errorCode`, `context`
`ESPCDFConfigError`	Thrown by `initCDF()` for missing or invalid config
`ESPCDFRegistryError`	Thrown by adaptor registry operations

Error codes

Registry errors

Code	When	Typical fix
`ADAPTOR_ALREADY_EXISTS`	Registering a duplicate `_identifier`	Check if adaptor already registered
`ADAPTOR_NOT_FOUND`	Calling `getAdaptor()`, `setActiveAdaptor()`, or `unregister()` with unknown ID	Verify adaptor was registered first
`ADAPTOR_METHOD_PROPERTY_NOT_IMPLEMENTED`	Calling an adaptor method that wasn't implemented	Check adaptor's interface implementation
`NO_ACTIVE_ADAPTOR_SET`	Calling `getActiveAdaptor()` before `setActiveAdaptor()`	Call `setActiveAdaptor()` first

Config errors

Code	When	Typical fix
`CDF_CONFIG_MISSING`	Calling `initCDF()` with empty/null config	Pass a valid registry: `initCDF({ sdkAdaptorRegistry })`

What it does​

How to use it​

Catch registry errors​

Catch config errors​

Error types​

Error class hierarchy​

Error codes​

Registry errors​

Config errors​

See also​