Overview
This node implements an intelligent caching mechanism designed to optimize workflow executions by storing and reusing data based on input content. It supports both individual item caching and batch mode caching, where all input items are processed as a single unit. The cache entries have configurable time-to-live (TTL) values, allowing automatic expiration of stale data.
Typical use cases include:
- Avoiding repeated expensive API calls or computations when the input data has not changed.
- Speeding up workflows by retrieving previously computed results from cache.
- Managing cache granularity by selecting specific fields for cache key generation.
- Forcing cache misses to refresh data when needed.
For example, if a workflow queries an external service with certain parameters, this node can cache the response keyed by those parameters. Subsequent runs with the same parameters will return cached results instantly unless forced to refresh.
Properties
| Name | Meaning |
|---|---|
| Batch Mode | Whether to process all input items together as a single cache unit, similar to "Run Once for All Items". |
| Force Miss | Whether to ignore existing cache entries and force regeneration of data, causing a cache miss every time. |
| Cache Key Fields | Comma-separated list of JSON fields from input items used to generate the cache key. If empty, the entire input item JSON is used for more precise caching. |
| TTL (Hours) | Time-to-live for cache entries in hours. Use 0 for infinite lifetime (no expiration). |
| Cache Directory | Filesystem directory path where cache files are stored. Must be writable by the n8n process. |
Output
The node has two outputs:
Cache Hit: Contains items retrieved from the cache. These are input items for which valid cached data was found and returned instead of recomputing or refetching.
Cache Miss: Contains items that were not found in the cache or were forced to regenerate due to TTL expiry or forced miss setting. These items should be processed downstream to generate fresh data, which can then be written back to the cache via the second input.
The output items maintain their original structure but represent either cached data (hit) or new data requiring processing (miss).
If binary data is involved, it would be stored within the cached JSON content, but the node primarily deals with JSON serialization/deserialization of cache entries.
Dependencies
- Requires access to the local filesystem to read/write cache files in the specified cache directory.
- Uses Node.js built-in modules:
cryptofor hashing,fsfor file operations,pathfor path handling, andassertfor validations. - No external API keys or services are required.
- The cache directory must be writable by the n8n process user.
Troubleshooting
Common Issues:
- Cache directory not writable or does not exist: Ensure the configured cache directory exists and has proper permissions.
- Cache key fields incorrectly specified: Invalid or non-existent fields may cause unexpected cache misses.
- Forced miss enabled unintentionally: This causes cache to be ignored, leading to no cache hits.
- Batch mode mismatch: Using batch mode requires consistent input structure; mixing batch and individual modes may cause errors.
Error Messages:
"Items cannot be empty": Occurs if the node tries to write cache with no input items. Provide valid input."Context not found in input data"or"Cache path not found in input data": Indicates internal state or paired item references missing, likely due to incorrect wiring or usage.- File system errors when reading/writing cache files: Check directory permissions and available disk space.
To resolve issues, verify node parameters, ensure correct input connections, and check filesystem accessibility.
Links and References
- Smart Cache GitHub Repository - Official documentation and source code.
- Node.js Crypto Module - Used for generating cache keys.
- Node.js FS Module - Used for file operations related to caching.