Error classes · MessageBuilder

Overview

All AIRich-specific errors extend AIRichError, which extends Error. Every error carries a .code property and extra metadata such as .availableIds.

customITEM_NOT_FOUNDDUPLICATE_IDINVALID_TARGETCONTENT_VALIDATION

Error table

Class	Code	Thrown when	Handling
AIRichError	custom	General internal conditions, such as a node that already has an ID (ALREADY_HAS_ID).	Inspect the code property and use it as the base error for general handling.
ItemNotFoundError	ITEM_NOT_FOUND	The ID referenced by replace, insertAt, peek, or delete does not exist.	Use err.availableIds to show valid IDs, then correct the target.
DuplicateIdError	DUPLICATE_ID	The supplied ID is already used by another node.	Ensure every addX call uses a unique ID. Call hasId() before assigning one.
InvalidTargetError	INVALID_TARGET	A target, index, or offset is out of range.	Validate the index against getIds().length and check the relative offset.
ContentValidationError	CONTENT_VALIDATION	A section, submessage, or table shape is invalid; or replace and insertAt are used together.	Match the expected schema and use only one of replace or insertAt per call.

Handling errors

errors.js

import {
  AIRichError,
  ItemNotFoundError,
  DuplicateIdError,
  InvalidTargetError,
  ContentValidationError,
} from './MessageBuilder.js';

try {
  rich.addText('Hello', { replace: 'missing-id' });
} catch (err) {
  if (err instanceof ItemNotFoundError) {
    console.log(err.code);          // ITEM_NOT_FOUND
    console.log(err.availableIds);  // list of valid IDs
  } else if (err instanceof AIRichError) {
    console.log('Rich error:', err.code);
  }
}

Safe patterns

Keep a list of valid IDs and show it when ITEM_NOT_FOUND occurs.
Use hasId() before assigning a new ID.
Never combine replace and insertAt in one call.
Validate user input before passing it to addTable() or addSubmessage().

Non-AIRich errors

Errors such as Socket is required, interactiveMessage not found, andCard must include an image are plain Error objects, not AIRichErrorsubclasses. Check the message and stack trace.

Do not swallow errors during build. A half-assembled payload is harder to debug than a failed send.