feat: normalise error logging to { message, error }

[cuzzlor]

However you log an error, you get the same record: { message: <the line you wrote>, error: { name, message, stack, … } }.

logger.error(new Error('boom')) //                      { level, message: 'boom',   error: { name, message, stack } }
logger.error('failed', new Error('boom')) //             { level, message: 'failed', error: { name, message, stack } }
logger.error('failed', { error: new Error('boom') }) //  { level, message: 'failed', error: { name, message, stack } }
logger.error(new Error('')) //                          { level, message: '',       error: { name, message, stack } }
logger.error(new AggregateError([inner])) //             { level, message: '',       error: { name, stack, errors: [ … ] } }

Interpolation is the deliberate exception: logger.error('failed: %s', err) passes the error as a value to interpolate, not as metadata, so it stays where the caller put it. More on that below.

The bug

An error with an empty message lost its name, stack and cause in the pretty console:

[error] 13:28:39.664 stop() threw during SIGTERM shutdown
[error] 13:28:39.666 [object Object]

Winston's single-argument hot path (winston/lib/winston/create-logger.js:78) reads:

const info = msg && msg.message && msg || { message: msg };

Whether the error becomes the record or is wrapped as { message: err } turns purely on whether its message is truthy. A truthy one takes the branch fix A in #148 handled; an empty one — a bare new Error(''), or an AggregateError whose detail is all in errors — takes the other. In the wrapped case the record is not an Error, so #148's branch never fired: the walk serialised the nested error correctly but left it under message, where prettyConsoleFormat interpolates an object and format.json emits message as an object where a log query expects a string.

Why nest rather than spread

The obvious fix was to spread the wrapped error onto the record, mirroring 2.1.0. That is wrong for both branches: it puts the error in the same namespace as level, defaultMeta and the caller's metadata, and the two overlap on name, message, stack, code, cause and errors. Whichever side wins, the other's data is dropped.

Measured with defaultMeta: { name: 'my-service' }:

Call	Record, before
logger.error(new Error('boom'))	{ name: 'my-service', message: 'boom', stack: 'my-service: boom …' }
logger.error(new Error(''))	{ name: 'my-service', message: '', stack: 'Error: …' }
logger.error('failed', { error: err })	{ name: 'my-service', message: 'failed', error: { name: 'Error', … } }

Both flat rows lose the error's name. The first also has its stack header rewritten to my-service: boom, because V8 formats stack lazily on first access and winston assigns defaultMeta onto the record before any format runs — which in that branch is the error itself. Only the third row survives, and it is the shape this library has always produced for a nested error. So that is the shape everything else normalises to.

Why normalise the arguments, not repair the record

A format only sees what winston has already built, and winston builds four unrelated records from an Error argument:

Call	Raw info	Error is
error(err)	{ level, …defaultMeta } — info is the error	the record
error(new Error(''))	{ message: <live Error>, level }	under message
error('failed', err)	{ message: 'failed boom', stack: '…', SPLAT: [err] }	in SPLAT, stack copied up
error('failed', { error: err })	{ message: 'failed', error: <live Error> }	already right

By the time a format runs, row 1 has had level and defaultMeta assigned onto the error instance, and row 3 has had the error's message concatenated onto the caller's — recoverable, if at all, only by guessing at a trailing substring.

So createLogger rewrites the arguments instead, and winston only ever sees row 4. normalizeErrorArgs moves an Error out of the message or metadata position into { error }, keeping the caller's message — or, for an error passed alone, its own. Metadata already there is merged; nothing is dropped, and a non-plain-object in the metadata position has { error } inserted before it rather than over it.

withNormalizedErrorArgs installs the wrappers as own properties shadowing the prototype methods they call, so the rest of the winston API is untouched. child needs no wrapping: winston builds one with Object.create(logger, { write }), so the wrappers are already on its prototype chain, and this is forwarded so a wrapped method called on a child still writes through the child.

This also closes the collision above. The error is never written as the record, so winston never assigns defaultMeta onto it — error.name stays Error and the stack header is never rewritten.

serializeErrorFormat keeps handling both record shapes: it is exported for use outside createLogger, and logger.write, winston's exception handlers and the object form of log all reach it without passing through a level method.

Interpolation is left alone

Winston reads the arguments after the message as interpolation values rather than metadata once the message matches formatRegExp, and merges nothing onto the record for such a call. Rewriting logger.error('failed: %s', err) therefore produced no top-level error at all, and put a { error } wrapper where format.splat() expects the error. Those calls now pass through untouched, so the error keeps the splat position it was given and serializeErrorFormat serialises it there.

An error in the message position needed the same guard for the opposite reason: its own message can hold a token by accident — new Error('bad format: %s') — which would have winston read the { error } just added as an interpolation value and drop it. Those are handed over as { message: err }, the shape the format already nests, and one winston cannot resolve back to a record that is the error.

Migration

Bumped to 2.2.0 — 2.1.0's top-level name/message/stack is one release old, which is what makes this the cheap moment to correct it. Documented in the README's error-serialization section:

• Read error.stack rather than stack, and adjust any omitPaths/redactPaths aimed at the old top-level keys.
• logger.error('msg', err) no longer has the error's message concatenated onto yours, and no longer copies stack to the top of the record: message is 'msg', detail is under error.

Verification

Driven end to end through createLogger with a colliding defaultMeta, capturing what the Console transport actually printed. All five call shapes above print the same way, and error.name/error.stack are intact where they used to be overwritten:

[error] 15:33:11.557 hello          # logger.error(new Error('hello'))
 name: my-service
 error:
  name: Error
  message: hello
  stack: Error: hello …

[error] 15:33:11.558 hello          # logger.error('hello', new Error('hello'))
 name: my-service
 error:
  name: Error
  message: hello
  stack: Error: hello …

• npm test — 143 passed (105 at 2.1.0)
• New coverage: the argument rewriting rules directly (merge, insert, no mutation, interpolation left alone, a token in the error's own message, DOMException, the message position for log(level, …), the object form of log left to the format, inheritance through Object.create); end to end, every call shape agreeing, a child logger, metadata alongside an error, the error instance left unmutated, the error kept in the splat position; and at the format level both record shapes, level staying out of error, routing symbols, and custom serialisers
• npm run build clean end to end — lint, tsc, rollup, attw, CJS smoke

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Fixes serialization of errors nested under message, preserving readable error details across Winston transports.

Changes:

• Hoists wrapped errors before recursive serialization.
• Adds coverage for empty-message and aggregate errors.
• Documents behavior and bumps version to 2.1.1.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/serialize-error-format.ts	Implements wrapped-error hoisting.
src/serialize-error-format.spec.ts	Adds regression tests.
README.md	Documents serialization behavior.
package.json	Bumps patch version.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cuzzlor]

Changing my mind on this one, hold fire.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.