# RetryOptions

**Kind:** Interface

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

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

`RetryOptions` configures retry behavior for the Kafka microservice client or consumer connection workflow. It controls retry timing, exponential backoff, retry limits, and whether the service should restart after a terminal failure.

## Properties

| Property | Type |
|---|---|
| `maxRetryTime` | `number` |
| `initialRetryTime` | `number` |
| `factor` | `number` |
| `multiplier` | `number` |
| `retries` | `number` |
| `restartOnFailure` | `(e: Error) => Promise<boolean>` |

## Diagram

```mermaid
graph LR
  A[Kafka operation fails] --> B[RetryOptions]
  B --> C{Retries remaining?}
  C -->|Yes| D[Wait initialRetryTime<br/>with factor and multiplier]
  D --> E[Retry operation]
  E --> A
  C -->|No| F[restartOnFailure(error)]
  F -->|true| G[Restart service or connection]
  F -->|false| H[Propagate failure]
```

## Usage

```ts
import type { RetryOptions } from '@nestjs/microservices';

const retryOptions: RetryOptions = {
  retries: 5,
  initialRetryTime: 300,
  maxRetryTime: 30_000,
  factor: 0.2,
  multiplier: 2,

  async restartOnFailure(error: Error): Promise<boolean> {
    console.error('Kafka connection failed:', error.message);

    // Restart only for recoverable infrastructure failures.
    return true;
  },
};

// Example: pass the options to Kafka transport configuration.
const kafkaOptions = {
  client: {
    clientId: 'orders-service',
    brokers: ['localhost:9092'],
    retry: retryOptions,
  },
};
```

## AI Coding Instructions

- Set `initialRetryTime`, `maxRetryTime`, `factor`, and `multiplier` together so backoff growth remains bounded.
- Use `retries` to prevent infinite retry loops; choose a limit appropriate for the service's availability requirements.
- Keep `restartOnFailure` asynchronous and return `true` only when restarting the Kafka client or process is safe.
- Log or report the received `Error` in `restartOnFailure` to preserve diagnostics for terminal connection failures.
- Reuse a shared retry configuration across Kafka client and consumer setup when consistent recovery behavior is required.

## How it works

`RetryOptions` is an exported KafkaJS-facing TypeScript interface. Its source file states that it is intended only to represent KafkaJS package types and must not contain NestJS logic. [packages/microservices/external/kafka.interface.ts:1-6](packages/microservices/external/kafka.interface.ts#L1-L6)

All of its properties are optional:

- `maxRetryTime?: number`
- `initialRetryTime?: number`
- `factor?: number`
- `multiplier?: number`
- `retries?: number`
- `restartOnFailure?: (e: Error) => Promise<boolean>` — an optional callback that receives an `Error` and asynchronously returns a boolean. [packages/microservices/external/kafka.interface.ts:253-260](packages/microservices/external/kafka.interface.ts#L253-L260)

`RetryOptions` can be assigned to the `retry` property of Kafka client configuration, producer configuration, and admin configuration. [packages/microservices/external/kafka.interface.ts:60-74](packages/microservices/external/kafka.interface.ts#L60-L74) [packages/microservices/external/kafka.interface.ts:110-119](packages/microservices/external/kafka.interface.ts#L110-L119) [packages/microservices/external/kafka.interface.ts:262-264](packages/microservices/external/kafka.interface.ts#L262-L264) Consumer configuration also accepts it through `retry`; that declaration additionally declares `restartOnFailure` with the same `Error`-to-`Promise<boolean>` signature. [packages/microservices/external/kafka.interface.ts:164-181](packages/microservices/external/kafka.interface.ts#L164-L181)

In Nest Kafka transport options, these configurations are exposed as `options.client`, `options.consumer`, and `options.producer`. [packages/microservices/interfaces/microservice-configuration.interface.ts:333-355](packages/microservices/interfaces/microservice-configuration.interface.ts#L333-L355) The client transport merges `options.client` into the Kafka constructor configuration, passes `options.consumer` to `client.consumer()`, and passes `options.producer` to `client.producer()`. [packages/microservices/client/client-kafka.ts:162-184](packages/microservices/client/client-kafka.ts#L162-L184) The server transport likewise merges `options.client` into the Kafka constructor configuration and passes its consumer and producer options to the respective Kafka client methods. [packages/microservices/server/server-kafka.ts:107-117](packages/microservices/server/server-kafka.ts#L107-L117) [packages/microservices/server/server-kafka.ts:155-162](packages/microservices/server/server-kafka.ts#L155-L162)

This interface itself contains no validation, defaults, error handling, or runtime side effects; it only declares the optional fields and their TypeScript types. [packages/microservices/external/kafka.interface.ts:253-260](packages/microservices/external/kafka.interface.ts#L253-L260)