winston

Postconditions — what we check

• createLogger · missing-error-listener

  warning
  WhencreateLogger() called without .on('error', handler) registered on the returned logger instance
  Returnslogger instance that silently swallows transport errors without error listener
  Required handlingCaller MUST attach an 'error' event listener to the logger instance immediately after createLogger(). Without it, transport failures (file system full, permission denied, network transport errors) are silently lost and logs may be dropped. Use: logger.on('error', (err) => { ... }). Source: Winston README — "the logger also emits an 'error' event if an error occurs within the logger itself which you should handle or suppress"
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1][2]
• query · query-unhandled-callback-error

  error
  Whenlogger.query() callback receives err as first argument when any transport query fails (e.g. File transport ENOENT/EACCES on log read, or transport does not support query method). Callers that omit the err check silently receive null/undefined results.
  Required handlingCaller MUST check the first argument to the callback: if (err) { handle or rethrow }. Ignoring err causes silent failures in log monitoring dashboards and audit UIs.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[3]
• transports.File · file-transport-missing-per-transport-error-listener

  warning
  Whennew transports.File() created without transport.on('error', handler). Filesystem errors (ENOSPC disk full, EACCES permission denied, ENOENT missing directory) during log writes are emitted on the transport instance itself — NOT on the parent logger. A logger.on('error') listener does not catch transport-level errors.
  Required handlingAfter creating a File transport, attach: transport.on('error', (err) => { ... }). This is separate from and required in addition to logger.on('error'). Without it, log file write failures are silently lost and logs are dropped without any alert.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[4][1]
• transports.File · file-transport-constructor-throws-on-invalid-options

  error
  Whennew transports.File() called with both 'stream' and 'filename'/'dirname' options simultaneously, or with neither a filename nor a stream. Constructor throws synchronously. When File transports are created dynamically (per-tenant log files, runtime-configured paths), uncaught throws crash the request handler.
  ThrowsError (synchronous, at construction time)
  Required handlingWrap dynamic new transports.File() calls in try/catch when filename is derived from runtime input. Validate that mutually exclusive options are not passed together.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• transports.Http · http-transport-warn-not-error-on-failure

  warning
  Whentransports.Http used without a 'warn' event listener. HTTP 4xx/5xx responses and connection errors trigger this.emit('warn', err) on the transport — not 'error'. Code that only attaches transport.on('error', handler) silently misses all network transport failures.
  Required handlingWhen using Http transport and log delivery reliability matters, attach both: transport.on('error', handler) AND transport.on('warn', handler). The 'warn' event carries network failures, not 'error'. Omitting the warn listener means silent log loss to remote aggregators.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[5]
• configure · configure-throws-on-v2-options

  error
  Whenlogger.configure() or createLogger() called with any of the removed winston@2 options: colors, emitErrs, formatters, padLevels, rewriters, stripColors. Throws synchronously with "{ colors, emitErrs, formatters, padLevels, rewriters, stripColors } were removed in winston@3.0.0." Migration codebases frequently pass both old and new options.
  ThrowsError — deprecated option keys present in configure options object
  Required handlingRemove all deprecated v2 option keys before passing to createLogger() or configure(). Use winston.format.* combinators instead of the removed formatters/padLevels/stripColors options. Wrap logger initialization in try/catch when config is loaded from external sources (env vars, config files) that may contain v2-era options.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][6]
• add · add-throws-on-non-objectmode-transport

  error
  Whenlogger.add() called with a transport that lacks _writableState.objectMode. Throws synchronously with "Transports must WritableStreams in objectMode." Typically surfaces when using third-party custom transports written for winston@2 (non-stream transports) not yet updated for @3.
  ThrowsError — transport is not a WritableStream in objectMode
  Required handlingWrap logger.add() in try/catch when transport type is not known at compile time. Verify third-party transports extend winston-transport (which sets objectMode: true) before dynamically adding them. For per-request transport patterns, validate transport instance before calling add().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/winstonjs/winstonhttps://github.com/winstonjs/winston#readme
2. [2]github.com/winstonjs/winstonhttps://github.com/winstonjs/winston/blob/master/README.md
3. [3]github.com/winstonjs/winstonhttps://github.com/winstonjs/winston/blob/master/lib/winston/logger.js
4. [4]github.com/winstonjs/winstonhttps://github.com/winstonjs/winston/blob/master/lib/winston/transports/file.js
5. [5]github.com/winstonjs/winstonhttps://github.com/winstonjs/winston/blob/master/lib/winston/transports/http.js
6. [6]github.com/winstonjs/winstonhttps://github.com/winstonjs/winston/blob/master/UPGRADE-3.0.md