feat(core): add namespace-based symbol branding for error class hierarchies (#10081)

Author: hntrl

.changeset/std-exceptions-namespace-branding.md

@@ -0,0 +1,20 @@
+---
+"@langchain/core": patch
+"@langchain/google": patch
+"@langchain/anthropic": patch
+"@langchain/openai": patch
+---
+
+feat(core): add namespace-based symbol branding for error class hierarchies
+
+Introduces `createNamespace` utility for hierarchical symbol-based branding of class hierarchies.
+All LangChain error classes now use this pattern, replacing hand-rolled duck-type `isInstance` checks
+with reliable cross-realm `Symbol.for`-based identity.
+
+- New `LangChainError` base class that all LangChain errors extend
+- New `createNamespace` / `Namespace` API in `@langchain/core/utils/namespace`
+- Refactored `ModelAbortError`, `ContextOverflowError` to use namespace branding
+- Added `ContextOverflowError.fromError()` static factory method
+- Deprecated `addLangChainErrorFields` in favor of `LangChainError` subclasses
+- Migrated Google provider errors (`GoogleError`, `ConfigurationError`, etc.) to namespace branding
+- Updated Anthropic and OpenAI providers to use `ContextOverflowError.fromError()`

libs/langchain-core/src/errors/index.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 import type { AIMessageChunk } from "../messages/ai.js";
+import { ns as baseNs } from "../utils/namespace.js";
 
 export type LangChainErrorCodes =
   | "CONTEXT_OVERFLOW"
@@ -13,6 +14,7 @@ export type LangChainErrorCodes =
   | "OUTPUT_PARSING_FAILURE"
   | "MODEL_ABORTED";
 
+/** @deprecated Subclass LangChainError instead */
 export function addLangChainErrorFields(
   error: any,
   lc_error_code: LangChainErrorCodes
@@ -22,75 +24,160 @@ export function addLangChainErrorFields(
   return error;
 }
 
+/** The error namespace for all LangChain errors */
+export const ns = baseNs.sub("error");
+
 /**
- * Error thrown when a model invocation is aborted via an AbortSignal.
- * Contains any partial output that was generated before the abort.
+ * Base error class for all LangChain errors.
+ *
+ * All LangChain error classes should extend this class (directly or
+ * indirectly). Use `LangChainError.isInstance(obj)` to check if an
+ * object is any LangChain error.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await model.invoke("hello");
+ * } catch (error) {
+ *   if (LangChainError.isInstance(error)) {
+ *     console.log("Got a LangChain error:", error.message);
+ *   }
+ * }
+ * ```
  */
-export class ModelAbortError extends Error {
-  readonly name = "ModelAbortError";
+export class LangChainError extends ns.brand(Error) {
+  readonly name: string = "LangChainError";
 
-  readonly lc_error_code = "MODEL_ABORTED";
+  constructor(message?: string) {
+    super(message);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Error class representing an aborted model operation in LangChain.
+ *
+ * This error is thrown when a model operation (such as invocation, streaming, or batching)
+ * is cancelled before it completes, commonly due to a user-initiated abort signal
+ * (e.g., via an AbortController) or an upstream cancellation event.
+ *
+ * The ModelAbortError provides access to any partial output the model may have produced
+ * before the operation was interrupted, which can be useful for resuming work, debugging,
+ * or presenting incomplete results to users.
+ *
+ * @remarks
+ * - The `partialOutput` field includes message content that was generated prior to the abort,
+ *   such as a partial AIMessageChunk.
+ * - This error extends the {@link LangChainError} base class with the marker `"model-abort"`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await model.invoke(input, { signal: abortController.signal });
+ * } catch (err) {
+ *   if (ModelAbortError.isInstance(err)) {
+ *     // Handle user cancellation, check err.partialOutput if needed
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ * ```
+ */
+export class ModelAbortError extends ns.brand(LangChainError, "model-abort") {
+  readonly name = "ModelAbortError";
 
   /**
-   * The partial message output that was accumulated before the abort.
-   * This allows callers to access whatever content was generated
-   * before the operation was cancelled.
+   * The partial message output that was produced before the operation was aborted.
+   * This is typically an AIMessageChunk, or could be undefined if no output was available.
    */
   readonly partialOutput?: AIMessageChunk;
 
+  /**
+   * Constructs a new ModelAbortError instance.
+   *
+   * @param message - A human-readable message describing the abort event.
+   * @param partialOutput - Any partial model output generated before the abort (optional).
+   */
   constructor(message: string, partialOutput?: AIMessageChunk) {
     super(message);
     this.partialOutput = partialOutput;
-    // Maintains proper stack trace for where our error was thrown (only available on V8)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, ModelAbortError);
-    }
-  }
-
-  /**
-   * Type guard to check if an error is a ModelAbortError
-   */
-  static isInstance(error: unknown): error is ModelAbortError {
-    return (
-      typeof error === "object" &&
-      error !== null &&
-      "name" in error &&
-      error.name === "ModelAbortError" &&
-      "lc_error_code" in error &&
-      error.lc_error_code === "MODEL_ABORTED"
-    );
   }
 }
 
 /**
- * Error thrown when input exceeds the model's context limit.
+ * Error class representing a context window overflow in a language model operation.
  *
- * This exception is raised by chat models when the input tokens exceed
- * the maximum context window supported by the model.
+ * This error is thrown when the combined input to a language model (such as prompt tokens,
+ * historical messages, and/or instructions) exceeds the maximum context window or token limit
+ * that the model can process in a single request. Most models have defined upper limits for the number of
+ * tokens or characters allowed in a context, and exceeding this limit will prevent
+ * the operation from proceeding.
+ *
+ * The {@link ContextOverflowError} extends the {@link LangChainError} base class with
+ * the marker `"context-overflow"`.
+ *
+ * @remarks
+ * - Use this error to programmatically identify cases where a user request, prompt, or input
+ *   sequence is too long to be handled by the target model.
+ * - Model providers and framework integrations should throw this error if they detect
+ *   a request cannot be processed due to its size.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await model.invoke(veryLongInput);
+ * } catch (err) {
+ *   if (ContextOverflowError.isInstance(err)) {
+ *     // Handle overflow, e.g., prompt user to shorten input or truncate text
+ *     console.warn("Model context overflow:", err.message);
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ * ```
  */
-export class ContextOverflowError extends Error {
+export class ContextOverflowError extends ns.brand(
+  LangChainError,
+  "context-overflow"
+) {
   readonly name = "ContextOverflowError";
 
-  readonly lc_error_code = "CONTEXT_OVERFLOW";
+  /**
+   * The underlying error that caused this {@link ContextOverflowError}, if any.
+   *
+   * This property is optionally set when wrapping a lower-level error using {@link ContextOverflowError.fromError}.
+   * It allows error handlers to access or inspect the original error that led to the context overflow.
+   */
+  cause?: Error;
 
-  constructor(message: string, options?: ErrorOptions) {
-    super(message, options);
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, ContextOverflowError);
-    }
+  constructor(message?: string) {
+    super(message ?? "Input exceeded the model's context window.");
   }
 
   /**
-   * Type guard to check if an error is a ContextOverflowError
+   * Creates a new {@link ContextOverflowError} instance from an existing error.
+   *
+   * This static utility copies the message from the provided error and
+   * attaches the original error as the {@link ContextOverflowError.cause} property,
+   * enabling error handlers to inspect or propagate the original failure.
+   *
+   * @param obj - The original error object causing the context overflow.
+   * @returns A new {@link ContextOverflowError} instance with the original error set as its cause.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await model.invoke(input);
+   * } catch (err) {
+   *   throw ContextOverflowError.fromError(err);
+   * }
+   * ```
    */
-  static isInstance(error: unknown): error is ContextOverflowError {
-    return (
-      typeof error === "object" &&
-      error !== null &&
-      "name" in error &&
-      error.name === "ContextOverflowError" &&
-      "lc_error_code" in error &&
-      error.lc_error_code === "CONTEXT_OVERFLOW"
-    );
+  static fromError(obj: Error): ContextOverflowError {
+    const error = new ContextOverflowError(obj.message);
+    error.cause = obj;
+    return error;
   }
 }