NATS JetStream icon

NATS JetStream

Manage NATS JetStream streams, consumers, and publish messages

Actions11

Overview

This node manages NATS JetStream streams, allowing users to update the configuration of existing streams. It connects to a NATS server with JetStream enabled and performs operations such as creating, updating, deleting streams, publishing messages, and managing consumers.

The Update Stream operation specifically modifies properties of an existing JetStream stream, such as its subjects, storage type, retention policy, message limits, and other advanced settings.

Common scenarios:

  • Adjusting stream configurations dynamically without downtime.
  • Changing subjects that a stream listens to as application requirements evolve.
  • Modifying storage or retention policies to optimize resource usage.
  • Updating replication factors for availability improvements.

Practical example:
You have a stream named "EVENTS" that collects order and inventory events. You want to add a new subject pattern events.payments and increase the maximum number of messages stored. Using this node's Update Stream operation, you can specify the new subjects list and max messages limit to apply these changes seamlessly.

Properties

Name Meaning
Stream Name The name of the JetStream stream to update. Must be an existing stream name (e.g., "EVENTS").
Stream Configuration A collection of configurable options for the stream:
- Subjects: List of subject patterns the stream will consume (supports wildcards like events.*).
- Description: Human-readable description.
- Storage Type: Either "File" (persistent) or "Memory" (non-persistent).
- Retention Policy: How messages are retained ("Limits", "Interest", or "Work Queue").
- Max Messages: Maximum total messages (-1 for unlimited).
- Max Messages Per Subject: Max messages per individual subject (-1 for unlimited).
- Max Age (Seconds): Max age of messages in seconds (0 for unlimited).
- Max Bytes: Max total size in bytes (-1 for unlimited).
- Max Message Size: Max size of individual messages (-1 for unlimited).
- Discard Policy: Whether to discard old messages or reject new ones when limits are reached ("Old" or "New").
- Number of Replicas: Number of replicas for the stream (1-5).
- Max Consumers: Max number of consumers (-1 for unlimited).
- Duplicate Window (Nanoseconds): Time window for duplicate detection (0 disables).
- No Acknowledgments: Boolean to disable acknowledgments for the stream.

Output

The node outputs JSON data representing the result of the update operation on the stream. This typically includes the updated stream configuration details returned by the JetStream management API.

Example output structure (simplified):

{
  "config": {
    "name": "EVENTS",
    "subjects": ["events.orders", "events.inventory"],
    "description": "Stream for order processing events",
    "storage": "file",
    "retention": "limits",
    "max_msgs": 100000,
    "max_bytes": 104857600,
    "discard": "old",
    "num_replicas": 3,
    ...
  },
  "state": {
    "messages": 50000,
    "bytes": 52428800,
    ...
  }
}

If the node supports binary data output (not indicated here), it would represent message payloads or attachments, but this operation focuses on stream metadata only.

Dependencies

  • Requires connection to a NATS server with JetStream enabled.
  • Needs an API key credential or equivalent authentication configured in n8n to connect securely to the NATS server.
  • Uses bundled NATS client libraries internally; no additional external dependencies required.
  • Proper permissions on the NATS server to manage streams are necessary.

Troubleshooting

  • Common issues:

    • Incorrect stream name: If the specified stream does not exist, the operation will fail.
    • Invalid configuration values: Providing unsupported or out-of-range values (e.g., replicas > 5) may cause errors.
    • Connection failures: Network issues or invalid credentials will prevent connecting to the NATS server.
    • Permission denied: Insufficient rights to modify streams on the server.

  • Error messages:

    • "Unknown stream operation: update": Indicates the operation is not recognized; ensure the node version supports this operation.
    • "NATS JetStream operation failed: ...": Generic failure message wrapping underlying errors; check inner error details.
    • Validation errors related to subjects or config fields will indicate which property is invalid.

  • Resolutions:

    • Verify stream existence and correct spelling.
    • Double-check all configuration parameters against JetStream documentation.
    • Confirm network connectivity and credential validity.
    • Ensure user roles on the NATS server allow stream updates.

Links and References

Discussion