KafkaJSErrorMetadata

Kind: Interface

Source: packages/microservices/external/kafka.interface.ts

Part of: Microservices

KafkaJSErrorMetadata describes additional context attached to KafkaJS-related errors in the microservices Kafka transport. It identifies whether an operation can be retried and provides the affected topic, partition, and Kafka partition metadata needed for diagnostics or recovery logic.

Properties

Diagram

mermaid
graph LR
  Error[KafkaJS Error] --> Metadata[KafkaJSErrorMetadata]
  Metadata --> Retriable[retriable: boolean]
  Metadata --> Topic[topic: string]
  Metadata --> Partition[partitionId: number]
  Metadata --> PartitionMetadata[metadata: PartitionMetadata]
  Retriable --> RetryLogic[Retry / Failure Handling]
  Topic --> Diagnostics[Logging and Diagnostics]
  Partition --> Diagnostics

Usage

ts
import type { KafkaJSErrorMetadata } from './kafka.interface';

function handleKafkaError(error: Error & Partial<KafkaJSErrorMetadata>) {
  if (!error.topic || error.partitionId === undefined) {
    throw error;
  }

  const context: KafkaJSErrorMetadata = {
    retriable: error.retriable ?? false,
    topic: error.topic,
    partitionId: error.partitionId,
    metadata: error.metadata!,
  };

  console.error(
    `Kafka error on ${context.topic}[${context.partitionId}]`,
    context.metadata,
  );

  if (context.retriable) {
    // Retry the Kafka operation using the topic and partition context.
    return;
  }

  throw error;
}

AI Coding Instructions

• Preserve the KafkaJS naming and metadata types when mapping Kafka errors into application-level error handling.
• Check retriable before scheduling retries; do not retry non-retriable errors automatically.
• Use topic and partitionId in logs, metrics, and tracing to make partition-specific failures diagnosable.
• Treat metadata as Kafka partition context and avoid replacing it with partial or unrelated metadata objects.