NATS

https://docs.nats.io/
Admin
NATS is a high-performance, open-source messaging system designed for microservices, cloud native...
Tokens:775,177
Snippets:5,861
Trust Score:9.6
Update:5 days ago
Show doc for...
Tokens:
Raw
### Java example setup

Source: https://docs.nats.io/concepts/getting-started.md

Run the examples from your IDE or command line where Java is installed. Clone the nats.java repository and navigate to the natsIoDoc examples directory.

```text
It's best to run the examples from your IDE or 

command line where Java is installed.



Clone https://github.com/nats-io/nats.java

and navigate to src/main/java/io/nats/examples/natsIoDoc
```

--------------------------------

### C#/.NET example setup

Source: https://docs.nats.io/concepts/getting-started.md

Run the examples from your IDE or command line where the .NET SDK is installed. Clone the nats.net repository and navigate to the Example.NatsIODocs examples directory.

```text
It's best to run the examples from your IDE or

command line where the .NET SDK is installed.



Clone https://github.com/nats-io/nats.net

and navigate to examples/Example.NatsIODocs
```

--------------------------------

### Install NATS Client Library for Go

Source: https://docs.nats.io/concepts/getting-started.md

Installs the official NATS client library for Go using go get.

```bash
go get github.com/nats-io/nats.go
```

--------------------------------

### C: Subscribe with wildcards (partial)

Source: https://docs.nats.io/concepts/subjects.md

Starts a C example showing a callback function for sensor messages. The snippet is incomplete; it only includes the function signature and the beginning of the printf statement.

```c
// Print which subscription pattern (passed as the closure) got the message

static void

onSensorMsg(natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)

{

    printf("%s%-15.*s (%s)\n",
```

--------------------------------

### Example output: configuration half

Source: https://docs.nats.io/learn/jetstream/your-first-stream.md

Shows the configuration half of the stream info output, including the header, Options, and Limits sections. The CLI turns direct get on by default, so that line appears here.

```text
Information for Stream ORDERS



                     Subjects: orders.>

                     Replicas: 1

                      Storage: File



Options:



                    Retention: Limits

              Acknowledgments: true

               Discard Policy: Old

             Duplicate Window: 2m0s



Limits:



             Maximum Messages: unlimited

          Maximum Per Subject: unlimited

                Maximum Bytes: unlimited

                  Maximum Age: unlimited

         Maximum Message Size: unlimited

            Maximum Consumers: unlimited
```

--------------------------------

### Example output of nats stream get

Source: https://docs.nats.io/learn/jetstream/get-direct.md

Example output from the CLI command showing the retrieved message metadata and JSON payload.

```text
Item: ORDERS#3 received 2026-05-22 10:14:31 +0000 UTC (36h2m05s) on Subject orders.shipped



{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:31Z"}
```

--------------------------------

### C: Get entry and handle missing key

Source: https://docs.nats.io/learn/key-value/your-first-bucket.md

C API example showing how to retrieve an entry, access its value, revision, and creation time, and check for `NATS_NOT_FOUND` when the key does not exist. The example prints the value and revision, and handles a missing key by printing a message.

```c
// A get returns an entry, not a bare value: the value together
// with its revision and the time it was written.

kvEntry *e = NULL;

s = kvStore_Get(&e, kv, "widget-blue");
if (s == NATS_OK)
{
    printf("value:    %.*s\n",
           kvEntry_ValueLen(e), (const char*) kvEntry_Value(e));
    printf("revision: %llu\n",
           (unsigned long long) kvEntry_Revision(e));
    printf("created:  %lld (unix seconds)\n",
           (long long) (kvEntry_Created(e) / 1000000000LL));
    kvEntry_Destroy(e);
    e = NULL;
}

// A key that was never put fails with NATS_NOT_FOUND, which is
// distinct from a key whose value is empty. Check for absence
// instead of treating a missing SKU as "the count is zero".
s = kvStore_Get(&e, kv, "widget-green");
if (s == NATS_NOT_FOUND)
{
    printf("widget-green not in stock yet\n");
    s = NATS_OK;
}
```

--------------------------------

### Expected JetStream server startup logs

Source: https://docs.nats.io/tutorials/build-an-app.md

The expected output when starting the server with JetStream enabled. It shows the server starting, JetStream starting, and the server being ready.

```text
[INF] Starting nats-server

[INF] Starting JetStream

[INF] Server is ready
```

--------------------------------

### Expected output when responder starts

Source: https://docs.nats.io/tutorials/request-reply.md

Example output shown when the responder starts listening on the 'time' subject.

```text
17:42:10 Listening on "time" in group "NATS-RPLY-22"
```

--------------------------------

### Go module setup and run commands

Source: https://docs.nats.io/tutorials/build-an-app.md

Commands to initialize the Go module, fetch the NATS client, and run the Go application.

```bash
go mod init orders-app

go get github.com/nats-io/nats.go

go run main.go
```

--------------------------------

### CONNECT message example

Source: https://docs.nats.io/reference/protocols/route.md

Example of a CONNECT message from a server's default string.

```text
CONNECT {"tls_required":false,"name":"wt0vffeQyoDGMVBC2aKX0b"}\r\n
```

--------------------------------

### CLI output: Direct Get message

Source: https://docs.nats.io/learn/jetstream/get-direct.md

Example output from the CLI direct get command. The '(direct)' marker indicates the message came from a server's local store over the Direct Get API, not from the leader through the regular read.

```text
Subscribing to JetStream Stream (direct) holding messages with subject orders.> starting with sequence 1

[#1] Received JetStream message (direct): stream: ORDERS seq 1 / subject: orders.created / time: 2026-05-22 10:14:22
```

--------------------------------

### C: Read server tags and create placed stream

Source: https://docs.nats.io/learn/clustering/placement.md

This C example reads the tags each server advertises via the $SYS.REQ.SERVER.PING.VARZ subject, then creates or updates the ORDERS stream with placement tags. It also prints the leader and replicas to confirm placement.

```c
// Read the tags each server actually advertises. Do not assume the
// config took — a typo in server_tags is silent until a placement
// asks for a tag no server carries. There is no dedicated client
// API for this: it is a plain request on the system account's
// $SYS.REQ.SERVER.PING.VARZ subject, filtered by server name. The
// "tags" field of the reply is the source of truth.
const char *names[] = {"n1-east", "n2-east", "n3-east"};



for (i = 0; (s == NATS_OK) && (i < 3); i++)
{
    natsMsg     *reply = NULL;
    char        req[64];



    snprintf(req, sizeof(req), "{\"server_name\":\"%s\"}", names[i]);
    s = natsConnection_RequestString(&reply, sysConn,
            "$SYS.REQ.SERVER.PING.VARZ", req, 2000);
    if (s == NATS_OK)
    {
        // Print just the "tags" list out of the VARZ reply.
        const char *tags = strstr(natsMsg_GetData(reply), "\"tags\":");
        const char *end  = (tags != NULL) ? strchr(tags, ']') : NULL;



        if (end != NULL)
            printf("%s %.*s]\n", names[i], (int)(end - tags), tags);
        natsMsg_Destroy(reply);
    }
}



// Now place ORDERS against exactly the tags you just read back.
// If a requested tag is misspelled or missing on every server, the
// intersection is empty and the create fails — it does NOT fall
// back to any server. The error names the tag no server carried:
//
//   no suitable peers for placement, tags not matched ['disk:sdd']
//   (error code 10005)
if (s == NATS_OK)
{
    jsStreamConfig  cfg;
    jsPlacement     placement;
    const char      *subjects[] = {"orders.>"};
    const char      *tags[]     = {"region:us-east", "disk:ssd"};



    jsPlacement_Init(&placement);
    placement.Tags    = tags;
    placement.TagsLen = 2;



    jsStreamConfig_Init(&cfg);
    cfg.Name        = "ORDERS";
    cfg.Subjects    = subjects;
    cfg.SubjectsLen = 1;
    cfg.Replicas    = 3;
    cfg.Placement   = &placement;



    s = js_AddStream(&si, js, &cfg, NULL, &jerr);
    if (jerr == JSStreamNameExistErr)
        s = js_UpdateStream(&si, js, &cfg, NULL, &jerr);
}



// Confirm the placement landed where you intended: the leader and
// both replicas are servers that advertised the tags.
if ((s == NATS_OK) && (si->Cluster != NULL))
{
    printf("Leader: %s\n", si->Cluster->Leader);
    for (i = 0; i < si->Cluster->ReplicasLen; i++)
        printf("Replica: %s\n", si->Cluster->Replicas[i]->Name);
}
```

--------------------------------

### Direct Get Batch (CLI)

Source: https://docs.nats.io/learn/jetstream/get-direct.md

Use the NATS CLI to fetch a batch of messages from a stream in a single Direct Get request, starting at a specified sequence number.

```APIDOC
## [CLI] nats sub --stream ORDERS --direct --start-sequence 1 --count 3

### Description
Fetches up to 3 messages from the ORDERS stream starting at sequence 1 in a single Direct Get request. The server streams them back without a round trip per message, and each message carries a Nats-Num-Pending header that counts down to 0 on the last one.

### Command
nats sub --stream ORDERS --direct --start-sequence 1 --count 3

### Parameters
- **--stream** (string) - Required - The name of the stream to read from.
- **--direct** (flag) - Required - Enables Direct Get mode.
- **--start-sequence** (integer) - Required - The stream sequence number to start from.
- **--count** (integer) - Required - The number of messages to fetch.

### Response
Each message includes a `Nats-Num-Pending` header indicating how many messages remain in the batch. The last message has a value of 0.

### Example Output
[#1] ... seq 1 ...   Nats-Num-Pending: 2
[#2] ... seq 2 ...   Nats-Num-Pending: 1
[#3] ... seq 3 ...   Nats-Num-Pending: 0
```

--------------------------------

### Example bcrypt hash output

Source: https://docs.nats.io/learn/security/authentication-basics.md

Example bcrypt hash output from the passwd command. The hash starts with $2a$11$ (Go's bcrypt prefix at cost 11).

```text
$2a$11$4I9tIK1JVbttZYtn.F.Jse5iY5ves4EtYWIpjlwyvgVYHJc8yTvk.
```

--------------------------------

### C: Create key with TTL and change TTL by delete/recreate

Source: https://docs.nats.io/learn/key-value/ttl-and-limits.md

C client example: configure the bucket with LimitMarkerTTL to enable per-key TTLs, create a key with a 30-minute TTL, then delete and recreate with a 10-minute TTL. Requires nats-server 2.11+.

```c
// Per-key TTL rides on the bucket's limit markers, so the bucket
// needs them enabled. The C client turns them on when the bucket is
// created: a LimitMarkerTTL > 0 enables per-key TTLs and is how long
// the bucket keeps an expiry marker. Requires nats-server 2.11+.

kvStore     *kv  = NULL;
uint64_t    rev  = 0;
kvConfig    cfg;



kvConfig_Init(&cfg);
cfg.Bucket         = "INVENTORY";
cfg.History        = 10;
cfg.LimitMarkerTTL = 60LL * 60 * 1000000000LL; // 1 hour, in nanoseconds



s = js_CreateKeyValue(&kv, js, &cfg);



// Create flash-sale with a 30-minute TTL (in milliseconds). The value
// removes itself 30 minutes later; no service has to clean it up.
// A TTL is accepted on create only: neither put nor update takes one.

if (s == NATS_OK)
    s = kvStore_CreateStringWithTTL(&rev, kv, "flash-sale", "99",
                                    30 * 60 * 1000);
if (s == NATS_OK)
    printf("created flash-sale at revision %" PRIu64 "\n", rev);



// A per-key TTL is create-only, and writing the key again appends a
// value with no TTL of its own. To change a TTL, delete the key and
// create it again with the new one.

if (s == NATS_OK)
    s = kvStore_Delete(kv, "flash-sale");
if (s == NATS_OK)
    s = kvStore_CreateStringWithTTL(&rev, kv, "flash-sale", "99",
                                    10 * 60 * 1000);
if (s == NATS_OK)
    printf("flash-sale now expires in 10 minutes\n");
```

--------------------------------

### Bad Config: Unquoted String Starting with Digit

Source: https://docs.nats.io/reference/config.md

Shows an invalid configuration where the token value '3secret' is unquoted, causing parsing issues because it starts with a digit. This example is labeled as 'Bad Config'.

```nats
listen: 127.0.0.1:4222

authorization: {

    # BAD!

    token: 3secret

}
```

--------------------------------

### Go: Direct Get batch with jetstreamext.GetBatch

Source: https://docs.nats.io/learn/jetstream/get-direct.md

Fetch up to 3 messages from ORDERS in a single Direct Get request, starting at stream sequence 1, and iterate them in order. Uses jetstreamext.GetBatch with GetBatchSeq(1).

```go
// Fetch up to 3 messages from ORDERS in a single Direct Get request,
// starting at stream sequence 1, and iterate them in order.

msgs, err := jetstreamext.GetBatch(ctx, js, "ORDERS", 3, jetstreamext.GetBatchSeq(1))

if err != nil {
	log.Fatalf("get batch: %v", err)
}

for msg, err := range msgs {
	if err != nil {
		log.Fatalf("read message: %v", err)
	}
	fmt.Printf("seq %d on %s\n", msg.Sequence, msg.Subject)
}
```

--------------------------------

### LS+ Examples

Source: https://docs.nats.io/reference/protocols/leafnode.md

Examples of LS+ usage: simple subscription, wildcard subscription with queue group, and wildcard with queue group and weight.

```plaintext
LS+ orders.new

```

```plaintext
LS+ orders.> fulfillment

```

```plaintext
LS+ orders.> fulfillment 4

```

--------------------------------

### Client loop to watch and get objects

Source: https://docs.nats.io/learn/object-store/watching-and-listing.md

In client code, the loop reads the watch, branches on the nil sentinel (the snapshot/live boundary) and keeps going, then issues a get only for the objects it needs. The example uses a watcher and a bucket.get_bytes call.

```python
for info in watcher:
    if info is None:                 # caught-up sentinel; keep reading
        continue
    if needs_bytes(info.name):       # only fetch what you actually use
        data = bucket.get_bytes(info.name)
```

--------------------------------

### JavaScript/TypeScript: Direct Get batch with jsm.direct.getBatch

Source: https://docs.nats.io/learn/jetstream/get-direct.md

Fetch up to 3 messages starting at stream sequence 1 in a single Direct Get request. Requires allow_direct on the stream and can be served by any replica, not just the leader. getBatch returns an iterator of stored messages in stream order.

```typescript
// Fetch up to 3 messages starting at stream sequence 1 in a single Direct Get
// request. This needs allow_direct on the stream and can be served by any
// replica, not just the leader. getBatch returns an iterator of stored
// messages in stream order.

const iter = await jsm.direct.getBatch("ORDERS", { seq: 1, batch: 3 });

for await (const m of iter) {
  console.log(`seq ${m.seq} on ${m.subject}`);
}
```

--------------------------------

### Install NATS Client Library for C#/.NET

Source: https://docs.nats.io/concepts/getting-started.md

Installs the NATS.Net client library via the dotnet CLI.

```bash
dotnet add package NATS.Net
```

--------------------------------

### Start NATS Server with Default Settings

Source: https://docs.nats.io/concepts/getting-started.md

Launches the NATS Server with default configuration, listening on the default client port.

```bash
nats-server
```

--------------------------------

### Go: Header-aware service and client request

Source: https://docs.nats.io/concepts/request-reply.md

Go example showing a service that echoes request headers in the response, and a client that sends a request with custom headers and reads the response headers.

```go
// Header Aware service

nc.Subscribe("service", func(msg *nats.Msg) {

	responseMsg := nats.NewMsg(msg.Reply)

	responseMsg.Data = msg.Data

	responseMsg.Header.Add("X-Response-ID", "123")

	responseMsg.Header.Add("X-Request-ID", msg.Header.Get("X-Request-ID"))

	responseMsg.Header.Add("X-Priority", msg.Header.Get("X-Priority"))

	nc.PublishMsg(responseMsg)

})



// Create message with headers

msg := nats.NewMsg("service")

msg.Header.Add("X-Request-ID", "123")

msg.Header.Add("X-Priority", "high")

msg.Data = []byte("data")



// Send request with headers

response, err := nc.RequestMsg(msg, time.Second)

if err == nil {

	fmt.Printf("Response: %s\n", response.Data)

	fmt.Printf("Response ID: %s\n", response.Header.Get("X-Response-ID"))

} else {

	fmt.Printf("Error: %s\n", err)

}
```

--------------------------------

### C#/.NET: Direct Get batch with GetBatchDirectAsync

Source: https://docs.nats.io/learn/jetstream/get-direct.md

Fetch up to three messages starting at stream sequence 1, in one request. The server streams the messages back in sequence order. On a direct get the stream sequence and original subject come back in headers, not in msg.Subject (which is the reply subject).

```csharp
// Fetch up to three messages starting at stream sequence 1, in one request.
var request = new StreamMsgBatchGetRequest
{
    Seq = 1,
    Batch = 3,
};



// The server streams the messages back in sequence order.
await foreach (NatsMsg<string> msg in js.GetBatchDirectAsync<string>("ORDERS", request))
{
    // On a direct get the stream sequence and original subject come back in
    // headers, not in msg.Subject (which is the reply subject).
    msg.Headers!.TryGetValue("Nats-Sequence", out var sequence);
    msg.Headers!.TryGetValue("Nats-Subject", out var subject);



    Console.WriteLine($"seq {sequence}: {subject}");
}
```

--------------------------------

### Create the INVOICES bucket with CLI

Source: https://docs.nats.io/learn/object-store/your-first-object.md

Creates a named object store bucket. The server provisions the backing JetStream stream automatically. The description is stored on the bucket.

```bash
#!/bin/bash

# Create the INVOICES bucket. A bucket is a named object store: hand it a
# name and a description and the server provisions the JetStream stream
# that backs it. `order-svc` will put invoice PDFs here; `warehouse` will
# get them before shipping.
#
# The --description text is stored on the bucket and shows up in
```

--------------------------------

### CONNECT message example from Go client

Source: https://docs.nats.io/reference/protocols/client.md

Example CONNECT message from the Go client's default string. Most clients set verbose to false by default, meaning the server does not confirm each message with +OK.

```plaintext
CONNECT {"verbose":false,"pedantic":false,"tls_required":false,"name":"","lang":"go","version":"1.2.2","protocol":1}␍␊
```

--------------------------------

### Rust: Direct Get batch with js.get_batch

Source: https://docs.nats.io/learn/jetstream/get-direct.md

Fetch up to 3 messages starting at stream sequence 1, all in one request. The batch arrives as a stream of messages in sequence order.

```rust
// Fetch up to 3 messages starting at stream sequence 1, all in one request.
let mut messages = js.get_batch("ORDERS", 3).sequence(1).send().await?;



// The batch arrives as a stream of messages in sequence order.
while let Some(msg) = messages.next().await {
    let msg = msg?;
    println!("seq {} on subject {}", msg.sequence, msg.subject);
}
```

--------------------------------

### Validate and start NATS server with nats-server -t -c nats.conf

Source: https://docs.nats.io/learn/security/encryption.md

Commands to check the configuration with nats-server -t -c nats.conf and then start the server with nats-server -c nats.conf. The boot log includes 'TLS required for client connections'. A plaintext client gets refused at the handshake; it never reaches authentication.

```bash
nats-server -t -c nats.conf
```

```bash
nats-server -c nats.conf
```

--------------------------------

### Create users with credential files

Source: https://docs.nats.io/learn/security/operator-mode.md

Creates one user per account and writes its creds file in the same step. Output shows the generated user nkeys.

```bash
nats auth user add order-svc ORDERS --defaults --credential order-svc.creds
```

```text
# User order-svc (UAKAFPCC4KDEKCAKP47VXHEYGHSL4GDET65EE7LMHMD2PCRAAWP37U2B)
```

```bash
nats auth user add analytics-reader ANALYTICS --defaults --credential analytics-reader.creds
```

--------------------------------

### Example /subsz response for orders.us.created

Source: https://docs.nats.io/learn/core-nats/debugging-delivery.md

Example JSON response from /subsz showing one matching subscription (orders.> on connection 8) for a publish to orders.us.created. num_subscriptions shows total subscriptions in the account, total shows matching count.

```json
{
  "num_subscriptions": 6,
  "total": 1,
  "offset": 0,
  "limit": 1024,
  "subscriptions_list": [
    { "account": "$G", "subject": "orders.>", "sid": "5", "msgs": 0, "cid": 8 }
  ]
}
```

--------------------------------

### Good Config: Quoted String Starting with Digit

Source: https://docs.nats.io/reference/config.md

Shows the corrected configuration where the token value is quoted as "3secret" to force it to be treated as a string. This example is labeled as 'Good Config'.

```nats
listen: 127.0.0.1:4222

authorization: {

    token: "3secret"

}
```
Tokens:
Raw