Logging Redis Errors in n8n: Step-by-Step Guide

Step by Step Guide for Logging Redis Errors in n8n

 

 

 

Who this is for: Developers and SREs running n8n in production who need full visibility into Redis‑related failures for debugging, compliance, and observability. For a complete overview of Redis usage, errors, performance tuning, and scaling in n8n, check out our detailed guide on Redis for n8n Workflows.

Quick Diagnosis

1. Set N8N_LOG_LEVEL=debug and N8N_REDIS_LOGGING=true in your n8n environment.
2. Add a custom logger in ~/.n8n/custom/logger.js that forwards Redis error events to your external log sink (e.g., Loki, Datadog, ELK).
3. Register the logger in ~/.n8n/custom/index.js with n8nCore.addErrorListener('redis', redisErrorHandler).
4. Restart n8n – every Redis error now appears in the n8n UI and in the external sink with full stack trace, command, and key name.

1. Why a Dedicated Redis‑Error Logger?

• Visibility – n8n’s default logger only shows “Redis error”, obscuring the root cause.
• Compliance – SOC‑2 / ISO‑27001 audits often require full error payloads to be retained.
• Correlation – Centralized observability lets you link Redis errors with workflow failures, CPU spikes, or network latency.

EEFA note: Never log raw Redis keys that contain PII. Mask or hash them before shipping to external services.

2. Prerequisites

Requirement	Minimum Version	Verify
n8n core	`0.250.0` (or later)	`n8n -v`
Node.js	`18.x` LTS	`node -v`
Redis client (ioredis)	`5.2+` (bundled)	`npm ls ioredis`
External log sink (optional)	–	Follow provider docs (Loki, Datadog, ELK)

Tip: Use the official n8n‑docker image for a reproducible environment; the steps below work identically on bare‑metal installs.

3. Enable Redis‑Error Emission in n8n

n8n does not expose Redis errors by default. Add two environment variables:

export N8N_LOG_LEVEL=debug      # Preserve full error objects
export N8N_REDIS_LOGGING=true   # Emit ‘redis’ events

EEFA warning: debug level logs can be noisy. In high‑traffic clusters, run a side‑car container that only forwards Redis logs to avoid overwhelming the main log stream. Facing connection issues with Redis in n8n? Explore our full n8n Redis guide for solutions and best practices.

4. Create a Custom Logger

4.1 Directory layout

~/.n8n/
├─ custom/
│  ├─ logger.js          # Redis‑error handler
│  └─ index.js           # Registers the handler with n8n core
└─ .env                  # Contains the two vars above

4.2 logger.js – core logic

Choose a transport (Loki example or fallback to console):

const { LokiTransport } = require('winston-loki');
const winston = require('winston');

const transport = process.env.LOG_SINK === 'loki'
  ? new LokiTransport({
      host: process.env.LOKI_URL,
      basicAuth: process.env.LOKI_AUTH,
      labels: { service: 'n8n', component: 'redis' },
    })
  : new winston.transports.Console();

Create the Winston logger:

const logger = winston.createLogger({
  level: 'error',
  format: winston.format.json(),
  transports: [transport],
});

Define the Redis error handler (masking PII in keys):

function redisErrorHandler(err, context) {
  const payload = {
    message: err.message,
    name: err.name,
    stack: err.stack,
    command: context.command,
    key: /email/.test(context.key) ? context.key.replace(/[^:]+$/, '***') : context.key,
    args: context.args,
    clientId: context.clientId,
    timestamp: new Date().toISOString(),
  };
  logger.error(payload);
}

Export the handler for registration:

module.exports = { redisErrorHandler };

4.3 index.js – hook into n8n core

const { redisErrorHandler } = require('./logger');
const { n8nCore } = require('n8n-core');   // internal API

// Register once on startup
n8nCore.addErrorListener('redis', redisErrorHandler);

EEFA note: n8nCore.addErrorListener is a private API. Pin your n8n version or test after each upgrade.

5. Wire the Custom Code into n8n

When using Docker, mount the custom folder and set N8N_CUSTOM_EXTENSIONS:

services:
  n8n:
    image: n8nio/n8n:0.250
    environment:
      - N8N_LOG_LEVEL=debug
      - N8N_REDIS_LOGGING=true
      - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom
      - LOG_SINK=loki
      - LOKI_URL=https://logs.example.com
      - LOKI_AUTH=base64(user:pass)

    volumes:
      - ./n8n-data:/home/node/.n8n
      - ./custom:/home/node/.n8n/custom
    ports:
      - "5678:5678"

Deploy with docker compose up -d. n8n loads index.js automatically and forwards any Redis error event to the chosen sink.

6. Verify the Pipeline

Step	Action	Expected Result
1	Trigger a known Redis error (e.g., GET on a key of the wrong type) via a test workflow	UI shows “Redis error” in the execution log
2	Query the external sink (Loki UI, Datadog) for service=n8n & component=redis	JSON payload with command, key, stack appears
3	Confirm masking – keys containing “email” appear as user:email:***	No raw email addresses in logs

Quick test workflow (Execute Command node)

{
  "nodes": [
    {
      "parameters": {
        "command": "GET",
        "key": "user:email:12345"
      },
      "name": "Redis Get (error)",
      "type": "n8n-nodes-base.redis",
      "typeVersion": 1,
      "position": [200, 300]
    }
  ],
  "connections": {}
}

Running this workflow generates a *WRONGTYPE* error that the custom logger captures. Learn how to handle Redis timeout issues in n8n effectively in our detailed n8n Redis guide.

7. Advanced: Correlating with Workflow Failures

Include the workflow execution ID in the log payload:

function redisErrorHandler(err, context) {
  const executionId = context?.executionId ?? 'unknown';
  const payload = { /* previous fields */ executionId };
  logger.error(payload);
}

Now you can query:

{service="n8n", component="redis", executionId="12345"}

to see which workflow triggered the Redis fault.

8. Common Pitfalls & Troubleshooting

Symptom	Likely Cause	Fix
No logs in external sink	`N8N_REDIS_LOGGING` not set or env not loaded	Verify with docker exec <container> printenv | grep N8N_REDIS_LOGGING
Duplicate log lines flood console	Transport set to Console **and** debug level prints the same error	Use new winston.transports.Console({ silent: true }) for UI‑only logging
Masking fails – raw PII still present	Regex too specific	Adopt a broader pattern or a dedicated PII‑scrubber library
Errors disappear after n8n upgrade	Private API addErrorListener changed	Pin n8n version (0.250.x) or migrate to the new n8nCore.on('redisError', …) event (check release notes)

9. Production‑Ready Checklist

• Set N8N_LOG_LEVEL and N8N_REDIS_LOGGING via immutable config (Docker secret, K8s ConfigMap).
• Store log‑sink credentials in a secret manager (AWS Secrets Manager, Vault).
• Review PII‑masking rules quarterly with the security team.
• Create an alert: fire when redis error count > 5 per minute (Grafana/Loki query).
• Configure log‑index retention (e.g., 30 days) to satisfy compliance.

 

Next Steps

1. Implement alerting on the log sink (e.g., Loki → Alertmanager).
2. Add structured metrics (Prometheus) for error rates (n8n_redis_error_total).
3. Explore batch shipping (e.g., winston-bulk) if your volume exceeds 10 k errors/min.

All commands assume a Unix‑like shell. Adjust paths for Windows PowerShell as needed.