What causes "Logger is required to handle rejections" in winstonjs/winston?

Pass an initialized logger: `new winston.RejectionHandler(logger)`.

winstonjs/winston · error · Error

Logger is required to handle rejections

Error message

Logger is required to handle rejections

What it means

RejectionHandler is the unhandled-rejection counterpart of ExceptionHandler: it captures unhandled promise rejections and routes them to a Logger's transports. Its constructor requires a Logger argument and throws when it is falsy, since a handler without a logger cannot record rejections.

Source

Thrown at lib/winston/rejection-handler.js:28

const os = require('os');
const asyncForEach = require('async/forEach');
const debug = require('@dabh/diagnostics')('winston:rejection');
const once = require('one-time');
const stackTrace = require('stack-trace');
const RejectionStream = require('./rejection-stream');

/**
 * Object for handling unhandledRejection events.
 * @type {RejectionHandler}
 */
module.exports = class RejectionHandler {
  /**
   * TODO: add contructor description
   * @param {!Logger} logger - TODO: add param description
   */
  constructor(logger) {
    if (!logger) {
      throw new Error('Logger is required to handle rejections');
    }

    this.logger = logger;
    this.handlers = new Map();
  }

  /**
   * Handles `unhandledRejection` events for the current process by adding any
   * handlers passed in.
   * @returns {undefined}
   */
  handle(...args) {
    args.forEach(arg => {
      if (Array.isArray(arg)) {
        return arg.forEach(handler => this._addHandler(handler));
      }

      this._addHandler(arg);

View on GitHub (pinned to ff0b79de85)

Solutions

Pass an initialized logger: `new winston.RejectionHandler(logger)`.
Prefer `logger.rejections.handle(transport)`, which wires the handler correctly.
Order initialization so the logger is created before rejection handling is installed.
Validate the logger reference before constructing.

Example fix

// before
const handler = new winston.RejectionHandler(loggerMaybeUndefined);

// after
if (!logger) throw new Error('Create logger before RejectionHandler');
const handler = new winston.RejectionHandler(logger);
// or simply:
logger.rejections.handle(new winston.transports.File({ filename: 'rejections.log' }));

Defensive patterns

Strategy: type-guard

Validate before calling

if (!logger || typeof logger.log !== 'function') {
  throw new TypeError('RejectionHandler requires a winston Logger instance');
}

Type guard

function isLogger(x) { return !!x && typeof x === 'object' && typeof x.log === 'function' && typeof x.rejections === 'object'; }

Try / catch

try {
  handler = new winston.RejectionHandler(logger);
} catch (err) {
  if (err.message === 'Logger is required to handle rejections') {
    logger.rejections.handle(fileTransport);
  } else { throw err; }
}

Prevention

Initialize the Logger before installing process-level rejection handling
Use `logger.rejections.handle(...)` instead of instantiating RejectionHandler directly
Centralize logger creation so handlers always receive a valid instance
Test bootstrap order in CI

When it happens

Trigger: Calling `new winston.RejectionHandler()` with no argument or an undefined/null logger — e.g. from custom rejection plumbing instead of `logger.rejections.handle(...)`.

Common situations: Manual setup of unhandledRejection handling during app bootstrap before the logger exists; refactors that removed logger initialization; typos/shadowed logger variables.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of winstonjs/winston@ff0b79de85 (2026-08-31). Data as JSON: /api/errors/1ca8a1dd036e823a. Report an issue: GitHub.