Deprecated: .unhandleExceptions() will be removed in winston

Q: What causes "Deprecated: .unhandleExceptions() will be removed in winston@4. Use .exceptions.unhandle()" in winstonjs/winston?

Replace logger.unhandleExceptions(handler) with logger.exceptions.unhandle(handler).

Error message

Deprecated: .unhandleExceptions() will be removed in winston@4. Use .exceptions.unhandle()

What it means

This is a deprecation warning emitted by winston's Logger.unhandleExceptions(). The method exists only for backwards compatibility with winston < 3.0.0 and simply forwards to logger.exceptions.unhandle(). It will be removed entirely in winston@4, so code relying on it will break on upgrade.

Source

Thrown at lib/winston/logger.js:627

   * @returns {undefined}
   * @deprecated
   */
  handleExceptions(...args) {
    // eslint-disable-next-line no-console
    console.warn(
      'Deprecated: .handleExceptions() will be removed in winston@4. Use .exceptions.handle()'
    );
    this.exceptions.handle(...args);
  }

  /**
   * Backwards compatibility to `exceptions.handle` in winston < 3.0.0.
   * @returns {undefined}
   * @deprecated
   */
  unhandleExceptions(...args) {
    // eslint-disable-next-line no-console
    console.warn(
      'Deprecated: .unhandleExceptions() will be removed in winston@4. Use .exceptions.unhandle()'
    );
    this.exceptions.unhandle(...args);
  }

  /**
   * Throw a more meaningful deprecation notice
   * @throws {Error} - TODO: add throws description.
   */
  cli() {
    throw new Error(
      [
        'Logger.cli() was removed in winston@3.0.0',
        'Use a custom winston.formats.cli() instead.',
        'See: https://github.com/winstonjs/winston/tree/master/UPGRADE-3.0.md'
      ].join('\n')
    );
  }

View on GitHub (pinned to ff0b79de85)

Solutions

Replace logger.unhandleExceptions(handler) with logger.exceptions.unhandle(handler).
Alternatively use logger.unhandleExceptions(false) semantics equivalent: logger.exceptions.unhandle(false) to unhandle without exiting.
Audit the codebase for .unhandleExceptions( occurrences and remove all before migrating to winston@4.

Example fix

// before
logger.unhandleExceptions(myExceptionHandler);
// after
logger.exceptions.unhandle(myExceptionHandler);

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast in dev/test if deprecated winston APIs are used
if (typeof logger.unhandleExceptions === 'function' && logger.unhandleExceptions !== logger.exceptions.unhandle) {
  // prefer the modern API
  const unhandle = logger.exceptions.unhandle.bind(logger.exceptions);
}

Type guard

function usesLegacyUnhandle(logger) {
  return typeof logger.unhandleExceptions === 'function';
}

Prevention

Always use the exceptions/rejections controller API (logger.exceptions.unhandle) in winston >= 3.
Run tests with NODE_OPTIONS=--pending-deprecation --trace-warnings to surface winston deprecations in CI.
Grep for legacy winston method names when upgrading major versions.

When it happens

Trigger: Calling logger.unhandleExceptions(...args) (typically with the same handler function previously passed to unhandleExceptions() or handleExceptions()) to stop catching uncaught exceptions instead of calling logger.exceptions.unhandle(...).

Common situations: Upgrading a winston 2.x codebase to winston 3.x and keeping the old API call; copying legacy logging setup snippets from older tutorials or internal boilerplate.

Related errors

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