NATS Debugging

Prerequisites

Install the NATS CLI:

brew install nats-io/nats-tools/nats

Connection shortcut:

alias nats-local='nats --server nats://127.0.0.1:4222'

Streams Overview

nats stream ls --server nats://127.0.0.1:4222

Streams: MESSAGE, INSTANCE, REACTION, SESSION_PROMPTS.

Inspect a Stream

nats stream info MESSAGE --server nats://127.0.0.1:4222

Shows subjects, retention policy, message count, consumer count, and first/last sequence.

Read Messages

Last message on a subject

nats stream get MESSAGE --server nats://127.0.0.1:4222 --last-for "message.received.>"

Specific sequence number

nats stream get MESSAGE --server nats://127.0.0.1:4222 --seq 5

Pretty-print JSON payload

nats stream get MESSAGE --server nats://127.0.0.1:4222 --seq 5 | python3 -c "
import sys, json
raw = sys.stdin.read()
start = raw.find('{')
if start >= 0:
    d = json.loads(raw[start:])
    print('METADATA:', json.dumps(d.get('metadata', {}), indent=2))
    print('PAYLOAD:', json.dumps(d.get('payload', {}), indent=2))
"

Consumer Status

All consumers with positions

nats consumer report MESSAGE --server nats://127.0.0.1:4222

The “ack floor” shows the last processed sequence number.

Ravi consumers

nats consumer report MESSAGE --server nats://127.0.0.1:4222 | grep ravi
nats consumer report INSTANCE --server nats://127.0.0.1:4222 | grep ravi

Consumer names: ravi-messages (MESSAGE), ravi-instances (INSTANCE), ravi-reactions (REACTION), ravi-prompts (SESSION_PROMPTS). Watch events in real time (plain NATS pub/sub, not JetStream):

# All message events
nats sub "message.received.>" --server nats://127.0.0.1:4222

# Specific instance
nats sub "message.received.whatsapp-baileys.<instanceId>" --server nats://127.0.0.1:4222

# Instance events (connect, disconnect, qr_code)
nats sub "instance.>" --server nats://127.0.0.1:4222

# All ravi internal events
nats sub "ravi.>" --server nats://127.0.0.1:4222

# Session responses
nats sub "ravi.session.*.response" --server nats://127.0.0.1:4222

# Tool executions
nats sub "ravi.session.*.tool" --server nats://127.0.0.1:4222

Replay Messages

Create a temporary consumer

Subscribe and receive all messages from a specific sequence:

nats consumer sub MESSAGE \
  --server nats://127.0.0.1:4222 \
  --filter "message.received.>" \
  --deliver-start-sequence 20 \
  --ack

Or from the beginning:

nats consumer sub MESSAGE \
  --server nats://127.0.0.1:4222 \
  --filter "message.received.>" \
  --deliver-all \
  --ack

Force reprocessing

Delete the ravi consumer and restart the daemon. Ravi recreates consumers with DeliverPolicy.New on startup:

nats consumer rm MESSAGE ravi-messages --server nats://127.0.0.1:4222
ravi daemon restart -m "recreate NATS consumers"

This only reprocesses new messages arriving after restart.

Check IngestMode

New messages should have ingestMode: "realtime". History-sync messages have ingestMode: "history-sync" and are skipped by ravi.

nats stream get MESSAGE --server nats://127.0.0.1:4222 --last-for "message.received.>" | \
  python3 -c "import sys,json; raw=sys.stdin.read(); d=json.loads(raw[raw.find('{'):]); print(d['metadata'].get('ingestMode','NOT SET'))"

Using `ravi events stream`

Ravi has a built-in event streaming command that wraps NATS subscriptions with formatting:

# Stream all events
ravi events stream

# Filter by pattern
ravi events stream -f "ravi.session.*"

# Hide noisy events
ravi events stream --no-claude --no-heartbeat

# Only show specific types
ravi events stream --only tool
ravi events stream --only prompt
ravi events stream --only audit

Using `ravi events replay`

Use replay for persisted JetStream history. It reads stored stream messages, applies filters, then prints a chronological slice:

# Last 15 minutes across all non-KV streams
ravi events replay

# Channel inbound messages in a fixed window
ravi events replay \
  --stream MESSAGE \
  --subject "message.received.>" \
  --since 2026-04-19T11:35:00Z \
  --until 2026-04-19T11:45:00Z

# Find one chat/session by substring and show raw payload
ravi events replay \
  --stream MESSAGE \
  --subject "message.received.>" \
  --chat "63295117615153@lid" \
  --contains "melhor plano" \
  --raw

# Reconstruct a session using session name/key plus its channel chat id
ravi events replay \
  --stream RAVI_EVENTS,MESSAGE,REACTION,SYSTEM \
  --session main-dm-615153 \
  --since 2h \
  --raw

# JSON path filters
ravi events replay \
  --stream MESSAGE \
  --where "payload.chatId=63295117615153@lid;payload.content.type=text"

Useful flags:

--stream MESSAGE,CUSTOM,SYSTEM
--subject "message.received.>"
--since 15m, --since 2026-04-19T11:35:00Z, or epoch milliseconds
--until 5m
--contains "text"
--where "path=value;path~=text;path!=value"
--session, --chat, --agent
--json or --raw

--session attempts to resolve a Ravi session locally. When found, it matches the session name, session key, and channel chat id, so a replay can include both internal session events from RAVI_EVENTS and channel events from MESSAGE/REACTION/SYSTEM. For complete session reconstruction, include RAVI_EVENTS. MESSAGE alone only captures channel events; it does not capture internal runtime events such as consumed prompts, turn interrupts, tool activity, responses, delivery, or abort requests. Delivery events use status: "delivered" | "failed" | "dropped" so replay can distinguish a sent response from a silent/drop/missing-target/send-error case.

Common Debugging Scenarios

Messages not arriving

Check if omni is publishing: nats sub "message.received.>" --server nats://127.0.0.1:4222
Check consumer position: nats consumer report MESSAGE --server nats://127.0.0.1:4222
Check ingestMode: history-sync messages are skipped
Check daemon logs: ravi daemon logs -f

Bot not responding

Check if prompts are being published: nats sub "ravi.session.*.prompt" --server nats://127.0.0.1:4222
Check SESSION_PROMPTS consumer: nats consumer report SESSION_PROMPTS --server nats://127.0.0.1:4222
Check if responses are being emitted: nats sub "ravi.session.*.response" --server nats://127.0.0.1:4222
Check Gateway delivery: ravi daemon logs -f | grep gateway

Trigger not firing

Check if events match the topic: nats sub "<trigger-topic>" --server nats://127.0.0.1:4222
Check cooldown: trigger may be in cooldown window
Check blocked topics: .prompt, .response, .claude topics are blocked
Test manually: ravi triggers test <id>

Messaging

Automation

Security

Integrations

Operations

NATS Debugging

Prerequisites

Streams Overview

Inspect a Stream

Read Messages

Last message on a subject

Specific sequence number

Pretty-print JSON payload

Consumer Status

All consumers with positions

Ravi consumers

Replay Messages

Create a temporary consumer

Force reprocessing

Check IngestMode

Using `ravi events stream`

Using `ravi events replay`

Common Debugging Scenarios

Messages not arriving

Bot not responding

Trigger not firing

​Prerequisites

​Streams Overview

​Inspect a Stream

​Read Messages

​Last message on a subject

​Specific sequence number

​Pretty-print JSON payload

​Consumer Status

​All consumers with positions

​Ravi consumers

​Live Subscribe

​Replay Messages

​Create a temporary consumer

​Force reprocessing

​Check IngestMode

​Using ravi events stream

​Using ravi events replay

​Common Debugging Scenarios

​Messages not arriving

​Bot not responding

​Trigger not firing

Prerequisites

Streams Overview

Inspect a Stream

Read Messages

Last message on a subject

Specific sequence number

Pretty-print JSON payload

Consumer Status

All consumers with positions

Ravi consumers

Live Subscribe

Replay Messages

Create a temporary consumer

Force reprocessing

Check IngestMode

Using `ravi events stream`

Using `ravi events replay`

Common Debugging Scenarios

Messages not arriving

Bot not responding

Trigger not firing