Overview
This node, JSON Database, allows you to read from and write to a JSON file that acts as a hierarchical key-value database. It is useful for scenarios where you need lightweight, file-based storage within your n8n workflows—such as persisting state, caching data between workflow runs, or maintaining simple structured records without setting up a full database server.
Practical examples:
- Storing user preferences or counters across workflow executions.
- Caching API responses to avoid redundant calls.
- Maintaining a list of processed items to prevent duplicates.
Properties
| Name | Meaning |
|---|---|
| Query Path | Path on which to act in the JSON tree (e.g., monsters["cookie-monster"].scares). Leave empty to select the root of the JSON structure. |
| File Path | Path to the JSON file to read/write data. Leave empty to use the default global database (JsonDatabase.Global.json in the node's directory). |
Output
The output is always a single field:
{
"data": <value>
}
- data: The value at the specified Query Path in the JSON file. This can be any valid JSON type (object, array, string, number, boolean, or null), depending on what is stored at that path.
If an error occurs and "Continue On Fail" is enabled, the output will instead be:
{
"error": "<error message>"
}
Dependencies
- File System Access: The node reads from and writes to files on the server where n8n is running. Ensure the n8n process has appropriate permissions for the target directories/files.
- No external services or API keys are required.
Troubleshooting
Common Issues
- File Permission Errors: If n8n does not have permission to read/write the specified file or directory, operations will fail.
- Database Lock Timeout: If the database file is locked by another process or operation for too long, you may see an error about the database being kept locked.
- Invalid Query Path: Supplying an invalid query path may result in undefined or unexpected data.
- Malformed JSON Input: When writing, if you provide an invalid JSON string as input, the node will throw a parsing error.
Error Messages
"The database is being kept locked for too much time. Try again later."
- Cause: Another process or previous operation did not release the lock on the database file.
- Solution: Wait and retry. Ensure no other processes are using the same file.
"Single item values cannot be assigned to the JSON root."
- Cause: Attempting to write a primitive value (string, number, boolean, or null) directly to the root of the JSON database.
- Solution: Write objects or arrays to the root, or specify a deeper query path for primitives.
File system errors (e.g., ENOENT, EACCES)
- Cause: File or directory does not exist, or insufficient permissions.
- Solution: Check the file path and permissions.