pino

Postconditions — what we check

• pino · destination-error

  error
  WhenThe destination stream emits an error event and no error handler is attached
  ThrowsUnhandled error event crashes the Node.js process
  Required handlingCaller MUST attach an error handler to custom destination streams. Use destination.on('error', handler) before passing to pino. pino.destination() streams are async-friendly but still emit errors on disk full, permissions, etc.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• pino · invalid-level

  error
  WhenAn invalid log level string is passed to pino() options.level
  ThrowsError: unknown level value
  Required handlingCaller MUST use valid level strings: 'trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent'. Invalid levels throw synchronously during logger construction.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• child · child-bindings-serializer-error

  error
  WhenA serializer applied to child bindings throws during child logger creation or first use
  ThrowsError from the serializer function
  Required handlingCaller MUST ensure serializers passed in child() bindings do not throw. Errors in child binding serializers propagate to the caller of child() or the first log call.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[1]
• transport · transport-error-event-unhandled

  error
  WhenThe transport worker thread emits an 'error' event and no error listener is attached to the returned ThreadStream.
  ThrowsUnhandled 'error' event crashes the Node.js process with an uncaught exception. This occurs when: (1) the transport worker thread crashes, (2) the worker process exits unexpectedly, (3) an unhandled rejection occurs inside the worker.
  Required handlingCaller MUST attach an error handler to the transport stream before passing it to pino(): const transport = pino.transport({ target: './my-transport' }); transport.on('error', (err) => { console.error('transport error:', err); process.exit(1); }); Per pino documentation: transport errors are NOT recoverable — terminate the process.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[2][3]
• transport · transport-module-not-found

  error
  WhenThe transport target module cannot be resolved (module not installed, wrong path, or typo in the target string).
  ThrowsError thrown synchronously at pino.transport() call time: "unable to determine transport target for \"<target-string>\"" or Node.js MODULE_NOT_FOUND error from require() resolution failure.
  Required handlingCaller MUST ensure the transport target is installed and the path/package name is correct. Catch the synchronous throw at startup: try { const transport = pino.transport({ target: 'pino-pretty' }); } catch (err) { console.error('Failed to start transport:', err.message); process.exit(1); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[3]
• transport · transport-target-targets-conflict

  error
  WhenBoth 'target' and 'targets' options are provided simultaneously to pino.transport().
  ThrowsError: "only one of target or targets can be specified" Thrown synchronously at pino.transport() call time.
  Required handlingUse either 'target' (single transport) or 'targets' (multi-transport array), never both.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[3]
• destination · destination-write-error-event

  error
  WhenThe SonicBoom destination stream encounters a write error (disk full, EACCES, EPERM, ENOENT on file path, fd closed) and no error listener is attached.
  ThrowsUnhandled 'error' event crashes the Node.js process. SonicBoom emits 'error' events on file open failure, write failure, and close failure — it never throws synchronously on write (to preserve throughput), but unhandled error events crash the process.
  Required handlingCaller MUST attach an error handler to the destination before use: const dest = pino.destination({ dest: '/var/log/app.log', sync: false }); dest.on('error', (err) => { console.error('log destination error:', err); // decide: fallback to stdout? terminate? alert ops? }); const logger = pino(dest);
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[4]
• flush · flush-callback-error-ignored

  warning
  Whenlogger.flush(cb) is called with a callback but the callback ignores the error parameter, OR flush is called without a callback and the underlying write fails.
  ThrowsThe callback is invoked with an Error object when the underlying stream flush fails (e.g., disk full, destination closed, EBADF). If no callback is provided and the flush fails, the error is silently swallowed (noop is used as the callback).
  Required handlingWhen flush correctness matters (e.g., graceful shutdown), always check the callback error: logger.flush((err) => { if (err) { console.error('flush failed:', err.message); // handle: retry, alert, or accept log loss } process.exit(0); });
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[5][4]
• multistream · multistream-invalid-stream-entry

  error
  WhenAn entry in the streams array does not implement the DestinationStream interface (missing write() method) or is not a valid StreamEntry object.
  ThrowsError: "stream object needs to implement either StreamEntry or DestinationStream interface" Thrown synchronously when the invalid entry is added via multistream() or add().
  Required handlingEnsure each stream entry has a write(msg: string): void method. Use pino.destination(), fs.createWriteStream(), or process.stdout directly.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[6]
• multistream · multistream-individual-stream-failure-silent

  warning
  WhenOne stream in a multistream configuration throws during write() (e.g., a SonicBoom stream destination has become invalid) while other streams are healthy.
  ThrowsThe write error from the failing stream propagates synchronously through multistream's write() function, which has no try-catch. This can drop log lines to ALL streams (not just the failing one) since write() aborts on first error.
  Required handlingWrap individual streams with error handling or use streams that emit 'error' events rather than throwing. Monitor individual destination health separately. Consider using pino.transport() with multiple targets instead — transports run in worker threads and isolate write failures from the main thread.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[6]

Sources

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

1. [1]github.com/pinojs/pinohttps://github.com/pinojs/pino/blob/main/docs/api.md
2. [2]raw.githubusercontent.com/pinojs/pinohttps://raw.githubusercontent.com/pinojs/pino/main/docs/transports.md
3. [3]github.com/pinojs/pinohttps://github.com/pinojs/pino/blob/main/lib/transport.js
4. [4]github.com/mcollina/sonic-boomhttps://github.com/mcollina/sonic-boom
5. [5]github.com/pinojs/pinohttps://github.com/pinojs/pino/blob/main/lib/proto.js
6. [6]github.com/pinojs/pinohttps://github.com/pinojs/pino/blob/main/lib/multistream.js