Smart Cache
Overview
The Smart Cache node provides intelligent caching capabilities for n8n workflows by storing and retrieving cache objects in an S3-compatible storage backend. It automatically generates cache keys based on input data or selected fields, supports time-to-live (TTL) expiration, and can operate in batch mode to process all input items as a single unit.
This node is beneficial in scenarios where expensive or slow operations produce repeatable results that can be reused, such as API calls, data transformations, or database queries. By caching these results, the node reduces redundant processing, improves workflow efficiency, and lowers external service usage.
Practical examples:
- Caching API responses keyed by request parameters to avoid repeated calls.
- Storing processed data chunks to speed up subsequent workflow runs.
- Using batch mode to cache aggregated results from multiple items at once.
Properties
| Name | Meaning |
|---|---|
| S3 Bucket | The name of the S3 bucket where cache objects are stored. |
| Path Prefix | Prefix for object keys inside the S3 bucket (e.g., "smartcache"). This organizes cached files under this path. |
| Batch Mode | Whether to process all input items as a single unit for caching, similar to "Run Once for All Items". |
| Force Miss | When enabled, forces cache misses so that data is regenerated and existing cache entries are ignored. |
| Cache Key Fields | Comma-separated list of JSON fields from input items used to generate the cache key. Leave empty to use the entire input item for more precise caching. |
| TTL (Hours) | Time-to-live for cache entries in hours. Use 0 for infinite (no expiration). |
Output
The node has two outputs:
Cache Hit: Contains items retrieved from the cache. These are the cached results corresponding to input items that matched existing cache entries and were still valid according to TTL.
Cache Miss: Contains items that were not found in the cache or whose cache entries expired. These items require further processing downstream and are typically written back to the cache after processing.
The output items maintain their original structure with a json field containing the data. The node does not output binary data.
Dependencies
- Requires access to an S3-compatible storage service with appropriate credentials (access key, secret key, optional session token, region, endpoint, etc.).
- The node expects valid S3 credentials configured in n8n.
- The specified S3 bucket must exist and be accessible.
- Uses SHA-256 hashing internally to generate cache keys based on input data or selected fields.
Troubleshooting
- Missing or invalid S3 credentials: The node will throw an error if S3 credentials are not provided or invalid. Ensure credentials are correctly set up in n8n.
- S3 bucket not specified or inaccessible: An error occurs if the bucket name is empty or the bucket cannot be accessed. Verify the bucket exists and permissions are correct.
- Empty input data: If both inputs ("Input" and "Write") are empty, the node returns early without processing.
- Incorrect paired item references: Write input items must come from the cache miss output; otherwise, errors about missing paired item indices occur.
- Force Miss enabled: When enabled, cache reads are bypassed, which may lead to increased processing time and storage usage.
- Cache expiration: If TTL is set and cache entries expire, those entries are treated as misses and regenerated.
- Network or permission issues with S3: Errors during cache read/write operations indicate connectivity or permission problems with the S3 backend.
Links and References
- Smart Cache GitHub Repository - Documentation and source code for the Smart Cache node.