NATS - JetStream Trigger icon

NATS - JetStream Trigger

Consumer JetStream stream message

NATS - JetStream Trigger

AI-generated

Overview

This node acts as a trigger for messages from a NATS JetStream stream consumer. It listens to a specified stream and consumer, then triggers workflow executions whenever new messages arrive. This is useful for workflows that need to react in real-time to events or data published on a JetStream message queue.

Common scenarios include:

  • Processing event-driven data streams such as logs, telemetry, or notifications.
  • Integrating with microservices architectures where services communicate via JetStream.
  • Automating workflows based on messages arriving in a JetStream queue.

For example, you could use this node to listen for new order messages on a stream and automatically start a workflow to process each order.

Properties

Name Meaning
Stream The name of the JetStream stream to listen to.
Consumer The name of the consumer within the stream to receive messages from.
Options Collection of additional options:
- Content Is Binary Whether to save the message content as binary data instead of JSON/text.
- Message Acknowledge When When to acknowledge the message to JetStream:
• Execution Finishes (regardless of success)
• Execution Finishes Successfully
• Immediately upon receipt
• Specified Later in Workflow (manual ack node)
- JSON Parse Body If true, parse the message body as JSON (only if content is not binary).
- Only Content If true, return only the content property of the message instead of the full message object (only if content is not binary).
- Parallel Message Processing Limit Maximum number of concurrent workflow executions triggered by messages. Use -1 for no limit. Must be greater than zero or -1.
To acknowledge an message from the consumer, insert a NATS - JetStream node later in the workflow and use the 'Acknowledge Message' operation Notice shown when "Specified Later in Workflow" acknowledgment option is selected, instructing how to manually acknowledge messages later in the workflow.

Output

The node outputs a JSON array with one item per received message. Each item contains:

  • json: The message data, which varies depending on options:
    • If Content Is Binary is enabled, the output includes a binary property containing the raw message data as binary.
    • Otherwise, the json property contains either the full message object or just the content, optionally parsed as JSON if enabled.

The output represents the message payload received from the JetStream consumer, ready for further processing in the workflow.

Dependencies

  • Requires connection to a NATS JetStream server.
  • Needs an API key or authentication credential configured in n8n to connect securely to the NATS server.
  • Uses the official NATS client library internally to consume messages.

Troubleshooting

  • Parallel Message Processing Limit Errors: Setting the parallel message processing limit to 0 or less than -1 will cause an error. Ensure it is set to -1 (no limit) or a positive integer.
  • Message Acknowledgment Issues:
    • If using manual acknowledgment ("Specified Later in Workflow"), forgetting to add the corresponding acknowledgment node later will cause messages to remain unacknowledged and potentially re-delivered.
    • Choosing immediate acknowledgment means messages are acknowledged before workflow execution, so failures won't trigger retries.
  • JSON Parsing Failures: Enabling JSON parsing on non-JSON message bodies will cause errors. Disable JSON parsing if message content is not valid JSON.
  • Binary Content Handling: If content is binary but JSON parsing or "Only Content" options are enabled, the node hides those options to prevent conflicts.
  • Connection Problems: Ensure the NATS server credentials and network connectivity are correctly configured.

Links and References

Discussion