Overview
This node acts as a trigger that subscribes to messages on specified NATS subjects. It listens for incoming messages matching a subject pattern and triggers workflows when such messages arrive. This is useful in event-driven architectures where workflows need to respond to real-time events published on a NATS messaging system.
Common scenarios include:
- Processing order updates or notifications by subscribing to order-related subjects.
- Load balancing message processing across multiple subscribers using queue groups.
- Reacting to user signup events or other domain-specific messages published on NATS.
For example, subscribing to the subject orders.> will trigger the workflow whenever any message related to orders (including subtopics) is published.
Properties
| Name | Meaning |
|---|---|
| Subject | Subject pattern to subscribe to. Supports wildcards: * for single token, > for multi-token. No spaces allowed. Example: orders.> |
| Queue Group | Optional group name for load balancing multiple subscribers. Only one subscriber in the group receives each message. Example: order-processors |
Output
The node outputs an array of JSON objects representing the received NATS messages. Each message object includes:
subject: The subject string on which the message was received.data: The payload of the message, typically a JSON object with relevant event data.headers: HTTP-like headers associated with the message.replyTo: A reply inbox string if applicable.timestamp: ISO string timestamp of when the message was received.
If triggered manually (for testing), it emits a sample message with dummy user signup data.
The node does not output binary data.
Dependencies
- Requires a connection to a NATS server, authenticated via an API key credential configured in n8n.
- Uses utility modules for managing NATS connections and validating subject and queue group formats.
- Relies on proper network access to the NATS server endpoint.
Troubleshooting
- Invalid subject pattern: If the subject contains spaces or invalid characters, the node will throw validation errors. Ensure the subject follows NATS syntax rules.
- Connection failures: Errors during connection setup may occur due to incorrect credentials, network issues, or server unavailability. Check the API key and network connectivity.
- Subscription errors: Permission errors or async errors from the NATS server are logged. Verify that the API key has sufficient permissions for the subscribed subjects.
- Load balancing issues: When using queue groups, only one subscriber in the group receives each message. If no messages are received, verify that the queue group name is consistent across subscribers.
Error messages provide context, e.g., "Failed to setup NATS subscriber" followed by the underlying error message.