Overview
This node interacts with the NATS JetStream Key-Value (KV) store, allowing users to manage KV buckets and keys within those buckets. Specifically, for the Key - Put operation, it stores or updates a value associated with a specified key inside a given KV bucket.
Typical use cases include:
- Storing configuration settings or user preferences in a centralized KV store.
- Caching data that can be quickly retrieved by other services.
- Managing hierarchical data structures using dot notation keys (e.g.,
user.123.settings).
For example, you might use this node to update a user's profile settings stored under the key user.123.settings in a bucket named app-config.
Properties
| Name | Meaning |
|---|---|
| Bucket Name | The name of the KV bucket to operate on. Must contain only letters, numbers, underscores, and hyphens (no spaces or dots). Example: user-preferences, app-config, cache-data. |
| Key | The key to store the value under. Supports dot notation for hierarchical organization (e.g., user.123.settings). Cannot contain spaces. Example: config.database.host, user.profile.avatar. |
| Value | The string value to store in the KV bucket under the specified key. Can be JSON or any string content. Example: {"name": "John", "age": 30}. |
Output
The node outputs an array of JSON objects corresponding to each input item processed. For the Put operation on a key, the output JSON typically contains the result of the put operation as returned by the underlying NATS KV API. This usually includes metadata about the stored key-value pair such as revision number, creation time, or confirmation of success.
If errors occur during processing, the output will include error details per item if the node is configured to continue on failure.
The node does not output binary data.
Dependencies
- Requires a connection to a NATS JetStream server with access to the KV store feature.
- Needs an API authentication credential configured in n8n to connect securely to the NATS server.
- Uses the bundled
nats-bundledlibrary for interacting with NATS. - Relies on utility modules for connection management, logging, and validation.
Troubleshooting
- Invalid Bucket Name: Bucket names must only contain letters, numbers, underscores, and hyphens. Spaces or dots are not allowed. If you get an error about bucket name validation, check your bucket name format.
- Unknown Operation or Resource: Errors like "Unknown key operation" or "Unknown resource" indicate misconfiguration of the operation or resource parameters. Verify you selected the correct resource (
key) and operation (put). - Connection Issues: Failure to connect to the NATS server may occur if credentials are incorrect or the server is unreachable. Ensure your API key and server URL are correctly set.
- Value Format: Although the value is a string, if you intend to store JSON, ensure it is properly serialized as a string before passing it.
- Continue On Fail: If enabled, the node will continue processing subsequent items even if one fails, returning error details in the output.