> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nats-io/nats-server/llms.txt
> Use this file to discover all available pages before exploring further.

# JetStream Options

> Configure JetStream for persistent messaging, streaming, and advanced message patterns

## Overview

JetStream is NATS's built-in persistence layer providing streaming, message replay, and exactly-once delivery semantics. These options control JetStream's behavior, storage limits, and performance characteristics.

## Command Line Flags

<ParamField path="-js, --jetstream" type="boolean" default="false">
  Enable JetStream functionality.

  ```bash theme={null}
  nats-server -js
  ```
</ParamField>

<ParamField path="-sd, --store_dir" type="string">
  Directory for JetStream storage files. If not specified, a temporary directory will be used.

  ```bash theme={null}
  nats-server -js -sd /var/lib/nats/jetstream
  ```
</ParamField>

## Configuration File Options

### Enabling JetStream

<ParamField path="jetstream" type="boolean" default="false">
  Enable JetStream in the configuration file.

  ```conf theme={null}
  jetstream {
    # JetStream enabled
  }
  ```
</ParamField>

### Storage Configuration

<ParamField path="jetstream.store_dir" type="string">
  Path to directory where JetStream will store data.

  ```conf theme={null}
  jetstream {
    store_dir: "/var/lib/nats/jetstream"
  }
  ```

  The directory will be created if it doesn't exist. Ensure the NATS server has write permissions.
</ParamField>

<ParamField path="jetstream.max_memory_store" type="integer">
  Maximum memory storage in bytes for memory-based streams. Default is 75% of available memory.

  ```conf theme={null}
  jetstream {
    max_memory_store: 1073741824  # 1 GB
  }
  ```
</ParamField>

<ParamField path="jetstream.max_file_store" type="integer">
  Maximum file storage in bytes for file-based streams. Default is calculated based on available disk space.

  ```conf theme={null}
  jetstream {
    max_file_store: 10737418240  # 10 GB
  }
  ```
</ParamField>

### Domain Configuration

<ParamField path="jetstream.domain" type="string">
  JetStream domain name for multi-tenancy and organizational separation.

  ```conf theme={null}
  jetstream {
    domain: "production"
  }
  ```

  Domains allow logical separation of JetStream resources across the same NATS infrastructure.
</ParamField>

### Sync and Performance

<ParamField path="jetstream.sync_interval" type="duration" default="2m">
  Interval for syncing data to disk (fsync). More frequent syncs increase durability but reduce performance.

  ```conf theme={null}
  jetstream {
    sync_interval: "30s"
  }
  ```
</ParamField>

<ParamField path="jetstream.sync_always" type="boolean" default="false">
  Sync to disk after every write. Maximizes durability but significantly impacts performance.

  ```conf theme={null}
  jetstream {
    sync_always: true
  }
  ```

  <Warning>Only enable for critical data where maximum durability is required.</Warning>
</ParamField>

<ParamField path="jetstream.compress_ok" type="boolean" default="false">
  Allow compression of stored data.

  ```conf theme={null}
  jetstream {
    compress_ok: true
  }
  ```
</ParamField>

<ParamField path="jetstream.unique_tag" type="string">
  Unique tag for this JetStream instance. Useful for identifying specific servers in clusters.

  ```conf theme={null}
  jetstream {
    unique_tag: "datacenter-1-rack-3-server-5"
  }
  ```
</ParamField>

### Advanced Limits

<ParamField path="jetstream.max_outstanding_catchup" type="integer">
  Maximum bytes for catching up consumers in clustered JetStream.

  ```conf theme={null}
  jetstream {
    max_outstanding_catchup: 33554432  # 32 MB
  }
  ```
</ParamField>

<ParamField path="jetstream.limits" type="object">
  Server-wide limits for JetStream operations.

  ```conf theme={null}
  jetstream {
    limits {
      max_ha_assets: 100
      max_request_batch: 256
    }
  }
  ```
</ParamField>

## Configuration Examples

### Basic JetStream Setup

```conf theme={null}
port: 4222
server_name: "nats-js-01"

# Enable JetStream
jetstream {
  store_dir: "/var/lib/nats/jetstream"
  max_memory_store: 1073741824    # 1 GB
  max_file_store: 10737418240     # 10 GB
}
```

### JetStream with Custom Sync

```conf theme={null}
port: 4222
server_name: "nats-js-sync"

jetstream {
  store_dir: "/mnt/ssd/nats/jetstream"
  max_memory_store: 2147483648    # 2 GB
  max_file_store: 53687091200     # 50 GB
  
  # Sync every 30 seconds for better durability
  sync_interval: "30s"
}
```

### High Durability Configuration

```conf theme={null}
port: 4222
server_name: "nats-js-durable"

jetstream {
  store_dir: "/data/nats/jetstream"
  max_memory_store: 536870912     # 512 MB
  max_file_store: 107374182400    # 100 GB
  
  # Maximum durability - sync every write
  sync_always: true
}
```

### Multi-Domain Setup

```conf theme={null}
port: 4222
server_name: "nats-js-domain"

jetstream {
  store_dir: "/var/lib/nats/jetstream"
  domain: "production"
  max_memory_store: 1073741824    # 1 GB
  max_file_store: 10737418240     # 10 GB
}
```

### Clustered JetStream

```conf theme={null}
port: 4222
server_name: "nats-js-cluster-01"

# Cluster configuration
cluster {
  name: "js-cluster"
  listen: "0.0.0.0:6222"
  routes: [
    "nats://nats-js-cluster-02:6222",
    "nats://nats-js-cluster-03:6222"
  ]
}

# JetStream with cluster-aware settings
jetstream {
  store_dir: "/var/lib/nats/jetstream"
  max_memory_store: 2147483648     # 2 GB
  max_file_store: 21474836480      # 20 GB
  unique_tag: "cluster-01"
  
  # Cluster-specific limits
  limits {
    max_ha_assets: 500
  }
}
```

### Performance Optimized

```conf theme={null}
port: 4222
server_name: "nats-js-perf"

jetstream {
  # Use fast SSD storage
  store_dir: "/mnt/nvme/nats/jetstream"
  
  max_memory_store: 4294967296     # 4 GB
  max_file_store: 107374182400     # 100 GB
  
  # Longer sync interval for higher throughput
  sync_interval: "5m"
  
  # Enable compression to save space
  compress_ok: true
}
```

## Storage Types

JetStream supports two storage types per stream:

### File Storage

Persistent storage on disk. Suitable for:

* Long-term message retention
* Large message volumes
* Durability requirements
* Message replay over extended periods

```bash theme={null}
# Create file-based stream
nats stream add ORDERS --storage file --subjects "orders.*"
```

### Memory Storage

In-memory storage. Suitable for:

* High-performance requirements
* Temporary data
* Lower latency needs
* Smaller message volumes

```bash theme={null}
# Create memory-based stream
nats stream add EVENTS --storage memory --subjects "events.*"
```

## Monitoring JetStream

### Server Status

Check JetStream status via monitoring endpoint:

```bash theme={null}
curl http://localhost:8222/jsz
```

### Account Statistics

View account-level JetStream usage:

```bash theme={null}
curl http://localhost:8222/jsz?acc=account_name
```

### Storage Usage

Monitor storage consumption:

```bash theme={null}
nats server info
```

## Best Practices

1. **Storage Location**: Use fast SSDs for `store_dir` to improve performance
2. **Capacity Planning**: Monitor storage usage and set appropriate `max_file_store` limits
3. **Memory Limits**: Set `max_memory_store` to prevent OOM errors
4. **Sync Strategy**: Balance `sync_interval` between durability and performance needs
5. **Clustering**: Use odd numbers of servers (3, 5) for JetStream clusters
6. **Backup**: Regularly backup the `store_dir` directory
7. **Domains**: Use domains to organize multi-tenant deployments
8. **Monitoring**: Monitor JetStream metrics via `/jsz` endpoint
9. **Disk Space**: Ensure sufficient disk space (2-3x `max_file_store`)
10. **Permissions**: Verify NATS process has read/write access to `store_dir`

## Limits and Quotas

JetStream enforces several limits:

* **Max Memory**: Total memory for memory-backed streams
* **Max Storage**: Total disk space for file-backed streams
* **Max Streams**: Number of streams per account (configurable)
* **Max Consumers**: Number of consumers per stream (configurable)
* **Max Message Size**: Individual message size limit

Configure account-level limits:

```conf theme={null}
accounts {
  APP: {
    jetstream: {
      max_memory: 1073741824      # 1 GB
      max_file: 10737418240       # 10 GB
      max_streams: 100
      max_consumers: 1000
    }
  }
}
```

## Troubleshooting

### Storage Issues

```bash theme={null}
# Check disk space
df -h /var/lib/nats/jetstream

# Verify permissions
ls -la /var/lib/nats/jetstream
```

### Performance Issues

* Increase `sync_interval` for higher throughput
* Use SSDs for `store_dir`
* Consider memory-backed streams for hot data
* Enable compression for large messages

### Cluster Issues

* Verify all cluster members have JetStream enabled
* Check that `store_dir` is unique per server
* Monitor `/jsz` for cluster state
* Ensure cluster connectivity via `/routez`

## Related Configuration

<CardGroup cols={2}>
  <Card title="Server Options" icon="server" href="/configuration/server-options">
    Core server configuration
  </Card>

  <Card title="Cluster Options" icon="network-wired" href="/configuration/cluster-options">
    Cluster JetStream for HA
  </Card>

  <Card title="TLS Options" icon="lock" href="/configuration/tls-options">
    Secure JetStream with TLS
  </Card>
</CardGroup>