# KafkaJSStaleTopicMetadataAssignmentMetadata

**Kind:** Interface

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

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

`KafkaJSStaleTopicMetadataAssignmentMetadata` describes stale Kafka topic metadata detected during partition assignment. It identifies the affected topic and lists partitions whose metadata is unknown or outdated, allowing the microservice transport layer to refresh topic metadata before retrying assignment or consumption operations.

## Properties

| Property | Type |
|---|---|
| `topic` | `string` |
| `unknownPartitions` | `PartitionMetadata[]` |

## Diagram

```mermaid
graph LR
  A[KafkaJSStaleTopicMetadataAssignmentMetadata] --> B[topic: string]
  A --> C[unknownPartitions: PartitionMetadata[]]
  C --> D[Partition 0 metadata]
  C --> E[Partition 1 metadata]
  C --> F[Additional unknown partitions]
```

## Usage

```ts
import type {
  KafkaJSStaleTopicMetadataAssignmentMetadata,
  PartitionMetadata,
} from './kafka.interface';

const staleMetadata: KafkaJSStaleTopicMetadataAssignmentMetadata = {
  topic: 'orders.created',
  unknownPartitions: [
    {
      partitionId: 2,
      leader: -1,
      replicas: [],
      isr: [],
    } as PartitionMetadata,
  ],
};

async function refreshStaleTopicMetadata(
  metadata: KafkaJSStaleTopicMetadataAssignmentMetadata,
) {
  console.warn(
    `Refreshing metadata for ${metadata.topic}; ` +
      `unknown partitions: ${metadata.unknownPartitions.map(
        ({ partitionId }) => partitionId,
      ).join(', ')}`,
  );

  // Refresh Kafka client/admin metadata before retrying assignment.
}
```

## AI Coding Instructions

- Populate `topic` with the exact Kafka topic name used by the producer or consumer configuration.
- Include only partitions with missing, unknown, or stale metadata in `unknownPartitions`.
- Treat this interface as diagnostic and retry metadata refresh or assignment after handling it.
- Preserve the `PartitionMetadata` structure returned by KafkaJS; avoid creating partial partition objects unless explicitly supported.
- Handle empty `unknownPartitions` safely when logging or deciding whether a metadata refresh is required.