# KafkaJSErrorMetadata

**Kind:** Interface

**Source:** [`packages/microservices/external/kafka.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/microservices/external/kafka.interface.ts#L1282)

**Part of:** [Microservices](subsystem-packages-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

| Property | Type |
|---|---|
| `retriable` | `boolean` |
| `topic` | `string` |
| `partitionId` | `number` |
| `metadata` | `PartitionMetadata` |

## 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.