# KafkaJSOffsetOutOfRangeMetadata

**Kind:** Interface

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

**Part of:** [Microservices](subsystem-packages-microservices)

`KafkaJSOffsetOutOfRangeMetadata` describes the Kafka topic and partition associated with an offset-out-of-range condition. It is used by the microservices Kafka integration to identify the exact partition that requires offset recovery, reset, or error handling.

## Properties

| Property | Type |
|---|---|
| `topic` | `string` |
| `partition` | `number` |

## Diagram

```mermaid
graph LR
  A[Kafka Consumer] --> B[Offset Out of Range Error]
  B --> C[KafkaJSOffsetOutOfRangeMetadata]
  C --> D[topic: string]
  C --> E[partition: number]
  C --> F[Offset Recovery / Retry Handling]
```

## Usage

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

function handleOffsetOutOfRange(
  metadata: KafkaJSOffsetOutOfRangeMetadata,
) {
  console.warn(
    `Offset is out of range for ${metadata.topic}[${metadata.partition}]`,
  );

  // Use the topic and partition to seek to a valid offset or apply recovery logic.
}

handleOffsetOutOfRange({
  topic: 'orders.created',
  partition: 2,
});
```

## AI Coding Instructions

- Provide a valid Kafka topic name in `topic`; do not use a consumer group ID or broker address.
- Use the numeric Kafka partition index in `partition`, typically starting at `0`.
- Preserve both fields when forwarding offset-out-of-range errors to recovery or logging code.
- Use this metadata with Kafka consumer offset reset or seek logic rather than treating it as a message payload.