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 systems that publish messages to JetStream for asynchronous processing.
- Building reactive workflows that respond immediately to incoming messages.
For example, you could use this node to listen to a stream of sensor data and trigger workflows that analyze or store the data as it arrives.
Properties
| Name | Meaning |
|---|---|
| Stream | The name of the JetStream stream to listen to. |
| Consumer | The name of the consumer within the stream that will receive messages. |
| Options | A collection of additional options: |
| Content Is Binary | Whether to save the message content as binary data instead of text. |
| JSON Parse Body | Whether to parse the message body as JSON into an object. |
| Message Acknowledge When | When to acknowledge the message receipt to JetStream. Options are: - Execution Finishes: after workflow execution finishes (success or failure). - Execution Finishes Successfully: only if execution succeeds. - Immediately: as soon as message is received. - Specified Later in Workflow: manual acknowledgment later in the workflow using a dedicated node. |
| Only Content | Whether to return only the content property of the message in the output, omitting other metadata. |
| Parallel Message Processing Limit | Maximum number of concurrent workflow executions triggered by messages. Use -1 for no limit. |
Note: If "Specified Later in Workflow" is chosen for message acknowledgment, a notice appears instructing to add a separate node to acknowledge messages manually.
Output
The node outputs JSON data representing the received JetStream message. Depending on options, the output can be:
- The full message object including metadata and content.
- Only the content property if "Only Content" is enabled.
- Parsed JSON object if "JSON Parse Body" is enabled.
- Binary data if "Content Is Binary" is enabled.
The output is emitted each time a message is received and processed according to the acknowledgment settings.
Dependencies
- Requires connection to a NATS server with JetStream enabled.
- Needs an API key credential configured in n8n for authenticating with the NATS server.
- Uses the internal NATS service client to consume messages from the specified stream and consumer.
Troubleshooting
- Parallel Message Processing Limit Errors: Setting the parallel message processing limit to 0 or less than -1 will cause an error. Ensure the value is greater than zero or -1 for unlimited.
- Acknowledgment Issues: Choosing manual acknowledgment ("Specified Later in Workflow") requires adding a separate node to acknowledge messages; otherwise, messages may remain unacknowledged and re-delivered.
- Connection Failures: Ensure the NATS server is reachable and credentials are correct.
- JSON Parsing Errors: If "JSON Parse Body" is enabled but the message content is not valid JSON, parsing will fail. Disable this option or ensure messages are valid JSON.
- Binary Content Handling: If "Content Is Binary" is enabled, downstream nodes must support binary data handling.