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.
Common scenarios where this node is beneficial include:
- Storing user preferences or session data in a distributed cache.
- Saving configuration settings dynamically that can be shared across services.
- Managing application state or feature flags in a centralized KV store.
For example, you might use this node to save a JSON object representing user settings under a key like 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 value to store in the KV bucket under the specified key. Typically a string but can represent structured data such as JSON. 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, which may include metadata about the stored key-value entry such as revision number, creation time, or confirmation of success.
If the node supports binary data output (not indicated here), it would summarize the meaning of the binary content accordingly. In this case, the output is purely JSON-based.
Dependencies
- Requires a connection to a NATS JetStream server with access to the Key-Value store feature.
- Needs an API authentication token or API key credential configured in n8n to establish the connection securely.
- Uses bundled NATS client libraries internally to perform operations.
- No additional external dependencies beyond the NATS server and credentials.
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 related to bucket name validation, check your bucket name format.
- Unknown Operation or Resource: Errors indicating unknown operations or resources suggest misconfiguration of the node parameters. Ensure the resource is set to "Key" and operation to "Put".
- Connection Issues: Failure to connect to the NATS server could be due to incorrect credentials or network issues. Verify your API key and server accessibility.
- Value Format Errors: Since the value is stored as a string, ensure that any JSON or structured data is properly serialized before input.
- Continue On Fail Behavior: If enabled, the node will continue processing subsequent items even if one fails, collecting errors in the output. Otherwise, it will stop execution on the first error.