Deprecated: .handleExceptions() will be removed in winston@4

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

Replace logger.handleExceptions(...) with logger.exceptions.handle(...) — same arguments, modern API.

Error message

Deprecated: .handleExceptions() will be removed in winston@4. Use .exceptions.handle()

What it means

logger.handleExceptions() is a winston < 3.0.0 backwards-compatibility shim. When called it warns that it will be removed in winston@4 and delegates to logger.exceptions.handle(). Code keeps working today but should migrate before the v4 release removes the method.

Source

Thrown at lib/winston/logger.js:614

      const info = typeof args[args.length - 1] === 'object' ? args.pop() : {};
      info.level = info.level || 'info';
      info.durationMs = time - timeEnd;
      info.message = info.message || id;
      return this.write(info);
    }

    this.profilers[id] = time;
    return this;
  }

  /**
   * Backwards compatibility to `exceptions.handle` in winston < 3.0.0.
   * @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);
  }

View on GitHub (pinned to ff0b79de85)

Solutions

Replace logger.handleExceptions(...) with logger.exceptions.handle(...) — same arguments, modern API.
Alternatively pass an 'exceptionHandlers' option object to winston.createLogger({...}).
Search the codebase for handleExceptions and update all call sites plus tests before upgrading to winston@4.

Example fix

// before
logger.handleExceptions(new winston.transports.File({ filename: 'exceptions.log' }));
// after
logger.exceptions.handle(new winston.transports.File({ filename: 'exceptions.log' }));

Defensive patterns

Strategy: validation

Validate before calling

// codemod: replace legacy call
// grep -rn 'handleExceptions(' src/ && update to exceptions.handle
function setupExceptions(logger, ...transports) {
  if (typeof logger.handleExceptions === 'function' && !logger.exceptions) {
    logger.handleExceptions(...transports); // winston v2 path
  } else {
    logger.exceptions.handle(...transports); // winston v3+
  }
}

Type guard

const needsMigration = (logger) => typeof logger.handleExceptions === 'function' && typeof logger.exceptions?.handle === 'function';

Prevention

Use logger.exceptions.handle() exclusively in new code.
Add an ESLint no-restricted-properties rule against handleExceptions.
Prefer declaring exceptionHandlers in createLogger options over post-hoc registration.

When it happens

Trigger: Any call to logger.handleExceptions(transport) or winston.handleExceptions(...) on a v3 logger — the warning fires on every invocation at logger.js:614.

Common situations: Upgraded winston 2.x codebases where handleExceptions was the standard way to catch uncaught errors; tutorials/docs predating v3; gradual migration where the deprecation warning is overlooked in logs.

Related errors

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