v2.2.1 - formatter fix (#23)

* Fix eight defects found by a contract test suite

doc.go states two things this package did not do: that it implements the Go2
error inspection design, and that every method works with any error type as well
as nil values. contract_test.go holds it to both, organised by obligation --
nothing panics, a message survives construction, the chain is walkable, Is and
As find what is there and only what is there, and the rendering paths neither
lose nor invent information. It found eight defects.

PANICS ON NIL. (*E).Error, (*E).Is and (*E).MarshalJSON dereferenced a nil
receiver. (*E).Is and the package-level Is also panicked whenever a frame
carried no annotation of its own, because reflect.TypeOf(nil) returns a NIL
reflect.Type and calling Comparable on that panics rather than answering false.
Both now share a comparableErrors helper that screens for it.

MESSAGE CORRUPTION. New and Wrap passed the message through fmt.Errorf, so any
message containing a percent sign was reinterpreted: New("100% complete")
produced "100%!c(MISSING)omplete" and "disk usage at 95%" produced
"...95%!(NOVERB)". Percent signs occur in URL-encoded values, percentages and
Windows paths -- ordinary text. A message is now stored verbatim; Errorf, and
Wrap when given arguments, still format.

MARSHAL PANIC. list() includes any error implementing Unwrap() error, so a
fmt.Errorf("%w") link in the chain reached an unguarded type assertion and a nil
field read. Marshalling an error must never panic: that path runs while
something is already failing, usually inside a logger.

TWO SEVERED CHAINS. Trace held the wrapped error in the annotation slot and left
prev nil, so Unwrap returned nothing and no sentinel below a trace was
reachable. Track built prev from a synthetic box whose own prev was nil, so for
anything that was not already an *E -- a fmt.Errorf("%w") wrapper, a joined
error, any foreign wrapping type -- everything beneath it was lost. A decorator
that adds caller data must not cost the caller their chain. Both now keep the
error on the Unwrap chain, and a frame with no message of its own renders
transparently rather than emitting a stray separator.

IS AND AS DISAGREED. WrapE's annotation is not on the Unwrap chain, and Is
special-cased it while As did not, so which of the two you reached for changed
the answer. (*E) now implements the standard As(interface{}) bool hook and the
package-level As searches the same slot.

The suite asserts agreement with the standard library as a PROPERTY across
sixteen chain shapes -- bdlm frames, fmt wrappers, foreign types, joined errors,
traced and tracked errors, and a foreign type whose Is hook answers false while
still wrapping a real cause -- rather than in hand-picked cases, since a
disagreement is exactly what leaves a caller unable to tell which function to
trust. It also covers depth 2000, concurrent reads under -race, and every
documented format verb.

Coverage 95.9%, go vet clean, race clean. Track's rendered message no longer
repeats the wrapped error's text, since the error it wraps renders immediately
after it.

Also corrects doc.go, which documented an errors.Has that does not exist -- Is
searches the whole chain, which is what that section described -- and showed
errors.Wrap(err, err2), which does not compile because Wrap takes a message
string.

* Match the standard library's As signature

As becomes As(err error, target interface{}) bool, replacing
As(err, test error) error. This is a breaking API change, hence v2.2.0.

The old form required the target to satisfy error, and that had two costs. A
caller could not ask for a bare interface type at all -- an interface pointer
does not itself implement error -- which is the most common real question to ask
of a chain: does anything in here implement this behaviour. And for concrete
types the target's receiver kind leaked into the call site: a type with a
pointer receiver could not be asked for, so callers chose value receivers to
make the call compile rather than because the type wanted one. This package's
own test helpers had done exactly that.

It also meant the central helper of a package that aims to implement the Go2
error inspection design did not match the standard library it mirrors, so code
moving between errors.As and bdlm/errors.As had to change shape as well as
import path.

Two behaviours now match the standard library exactly. As panics on a target
that is not a non-nil pointer to an error-implementing type or to an interface:
such a target can never match anything, so answering "not found" would hide a
call-site mistake in the paths hardest to observe. A nil ERROR remains an
ordinary false, which is the opposite case -- a runtime condition rather than a
programming error, and the standard library draws the same line.

The walk also no longer ends on a hook that answers false. It read
`if e, ok := err.(interface{ As(error) error }); ok { return e.As(test) }`, so
the first link with an As method decided the whole search -- the same defect
that was fixed in Is, in the same shape. It is now `ok && x.As(target)`.

Tests cover the panic contract across four unusable target shapes, interface
targets, pointer- and value-receiver concrete targets, and agreement with the
standard library on every chain shape using an identical call for both -- which
is itself the point of the change. Coverage 97.3%, vet clean, race clean.

The As(interface{}) bool hook on *E is unchanged and is what reaches the
annotation slot, so Is and As continue to agree about what the chain contains.

* Make %v carry the cause chain, like Error() and %s

Error() and %s returned "outer: middle: root cause". %v returned "outer". The
cause was preserved everywhere except the verb that fmt.Println uses and that
most loggers call, so a wrapped error was recorded in full and rendered
truncated -- which is the shape of the rollup failure that started this: the
ClickHouse cause was present on the error and absent from the log line.

fmt normally gives %v on an error the value of Error(), but implementing
Formatter overrides that, and Format's 'v' case took a separate path through the
per-frame message and stopped at the first frame. The 'default' case, which
serves %s and %q, called Error() and was correct all along. Both the standard
library and pkg/errors treat %v as the whole chain, so this package was the
outlier.

%v, %s, %-v and %#v now render the full message. %+v and %#+v are unchanged and
still print one line per frame carrying that frame's own message: the tail would
otherwise repeat on every line, and that separation is the whole reason the
trace forms exist.

This changes rendered output, hence v2.2.1 and a note in the changelog for
anyone asserting on log text. Eight examples encoded the old behaviour and are
updated. The four trace examples were unaffected, which is the evidence that the
change is scoped to the non-trace forms -- I briefly broke one by editing
expectations positionally rather than by function, and it failed immediately.

TESTS. The suite had a gap that let this through, and it is worth naming because
the gap was in the assertions rather than the coverage: TestFormatVerbs checked
that every verb produced something non-empty, contained no malformed directive,
and that %+v was longer than %v. All three pass while %v silently drops the
cause. Asserting SHAPE is not asserting BEHAVIOUR. TestPlainVerbsEqualError now
requires %v and %s to equal Error() across eight chain shapes, and
TestTraceVerbKeepsOneMessagePerFrame requires the trace form to state each
message exactly once, so neither form can drift into the other.

Coverage 96.9%, vet clean, race clean.

Author: mkenney

CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - **Minor**: feature additions, removal of deprecated features
 - **Patch**: bug fixes, backward compatible model and function changes, etc.
 
+# v2.2.1 - 2026-08-24
+#### Fixed
+* **`%v` discarded the cause chain.** `Error()` and `%s` returned the full message, while `%v`
+  printed only the outermost frame — so a wrapped cause was recorded everywhere except where anyone
+  looks for it. `%v` is the verb `fmt.Println(err)` uses and the one most loggers call.
+
+
 # v2.2.0 - 2026-08-21
 #### Changed
 * **`As` now matches the standard library's signature**, `As(err error, target interface{}) bool`,

contract_test.go

@@ -348,7 +348,60 @@ func TestFormatVerbs(t *testing.T) {
 		})
 	}
 	if plain, trace := fmt.Sprintf("%v", err), fmt.Sprintf("%+v", err); len(trace) <= len(plain) {
-		t.Errorf("%%+v (%d bytes) should carry more than %%v (%d bytes)", len(trace), len(plain))
+		t.Errorf("the trace verb (%d bytes) should carry more than the plain one (%d bytes)", len(trace), len(plain))
+	}
+}
+
+// TestPlainVerbsEqualError is the assertion that matters most and the one this suite was missing.
+//
+// %v and %s on an error must both produce Error(). fmt gives that for free, but a Formatter
+// overrides it -- and this package's Formatter took a separate path for 'v' that printed only the
+// outermost frame, so %v silently discarded the cause while %s and Error() kept it. Every check
+// this suite already had passed anyway: the output was non-empty, contained no bad verb, and was
+// shorter than %+v. Asserting SHAPE rather than equivalence is what let it through.
+//
+// %v is also the verb loggers use, so the effect was a wrapped cause being recorded everywhere
+// except where anyone would look for it.
+func TestPlainVerbsEqualError(t *testing.T) {
+	shapes := map[string]error{
+		"single frame":        errors.New("only"),
+		"two frames":          errors.Wrap(errors.New("inner"), "outer"),
+		"three frames":        errors.Wrap(errors.Wrap(errors.New("root"), "middle"), "outer"),
+		"over a sentinel":     errors.Wrap(sentinel, "outer"),
+		"over a foreign type": errors.Wrap(&custom{msg: "foreign"}, "outer"),
+		"over fmt wrapping":   errors.Wrap(fmt.Errorf("f: %w", sentinel), "outer"),
+		"annotation only":     errors.WrapE(sentinel, nil),
+		"traced":              errors.Trace(errors.Wrap(sentinel, "inner")),
+	}
+	for name, err := range shapes {
+		t.Run(name, func(t *testing.T) {
+			want := err.Error()
+			if got := fmt.Sprintf("%v", err); want != got {
+				t.Errorf("the plain verb = %q, want Error() = %q", got, want)
+			}
+			if got := fmt.Sprintf("%s", err); want != got {
+				t.Errorf("the string verb = %q, want Error() = %q", got, want)
+			}
+		})
+	}
+}
+
+// TestTraceVerbKeepsOneMessagePerFrame is the other half: the trace form prints a line per frame,
+// so each line must carry only its OWN message. If it used the full chain the tail would repeat on
+// every line, which is what makes the two forms different rather than one being a longer version of
+// the other.
+func TestTraceVerbKeepsOneMessagePerFrame(t *testing.T) {
+	err := errors.Wrap(errors.Wrap(errors.New("root"), "middle"), "outer")
+	trace := fmt.Sprintf("%+v", err)
+
+	if strings.Count(trace, "root") != 1 {
+		t.Errorf("the root message appears %d times; each frame should state its own message once:\n%s",
+			strings.Count(trace, "root"), trace)
+	}
+	for _, frame := range []string{"outer", "middle", "root"} {
+		if !strings.Contains(trace, frame) {
+			t.Errorf("the trace is missing frame %q", frame)
+		}
 	}
 }
 

examples_test.go

@@ -20,19 +20,19 @@ func ExampleNew() {
 func ExampleE_Format_string() {
 	err := loadConfig()
 	fmt.Println(err)
-	// Output: service configuration could not be loaded
+	// Output: service configuration could not be loaded: could not decode configuration data: could not read configuration file: read: end of input
 }
 
 func ExampleE_Format_stringPreformat() {
 	err := loadConfig()
 	fmt.Printf("% v", err)
-	// Output: service configuration could not be loaded
+	// Output: service configuration could not be loaded: could not decode configuration data: could not read configuration file: read: end of input
 }
 
 func ExampleE_Format_stringDetail() {
 	err := loadConfig()
 	fmt.Printf("%-v", err)
-	// Output: service configuration could not be loaded - #0 mocks_test.go:16 (github.com/bdlm/errors/v2_test.loadConfig);
+	// Output: service configuration could not be loaded: could not decode configuration data: could not read configuration file: read: end of input - #0 mocks_test.go:16 (github.com/bdlm/errors/v2_test.loadConfig);
 }
 
 func ExampleE_Format_stringTrace() {
@@ -44,7 +44,7 @@ func ExampleE_Format_stringTrace() {
 func ExampleE_Format_stringDetailPreformat() {
 	err := loadConfig()
 	fmt.Printf("% -v", err)
-	// Output: service configuration could not be loaded - #0 mocks_test.go:16 (github.com/bdlm/errors/v2_test.loadConfig);
+	// Output: service configuration could not be loaded: could not decode configuration data: could not read configuration file: read: end of input - #0 mocks_test.go:16 (github.com/bdlm/errors/v2_test.loadConfig);
 }
 func ExampleE_Format_stringTracePreformat() {
 	err := loadConfig()
@@ -58,23 +58,23 @@ func ExampleE_Format_stringTracePreformat() {
 func ExampleE_Format_json() {
 	err := loadConfig()
 	fmt.Printf("%#v", err)
-	// Output: [{"error":"service configuration could not be loaded"}]
+	// Output: [{"error":"service configuration could not be loaded: could not decode configuration data: could not read configuration file: read: end of input"}]
 }
 
 func ExampleE_Format_jsonPreformat() {
 	err := loadConfig()
 	fmt.Printf("% #v", err)
 	// Output: [
 	//     {
-	//         "error": "service configuration could not be loaded"
+	//         "error": "service configuration could not be loaded: could not decode configuration data: could not read configuration file: read: end of input"
 	//     }
 	// ]
 }
 
 func ExampleE_Format_jsonDetail() {
 	err := loadConfig()
 	fmt.Printf("%#-v", err)
-	// Output: [{"caller":"#0 mocks_test.go:16 (github.com/bdlm/errors/v2_test.loadConfig)","error":"service configuration could not be loaded"}]
+	// Output: [{"caller":"#0 mocks_test.go:16 (github.com/bdlm/errors/v2_test.loadConfig)","error":"service configuration could not be loaded: could not decode configuration data: could not read configuration file: read: end of input"}]
 }
 
 func ExampleE_Format_jsonDetailPreformat() {
@@ -83,7 +83,7 @@ func ExampleE_Format_jsonDetailPreformat() {
 	// Output: [
 	//     {
 	//         "caller": "#0 mocks_test.go:16 (github.com/bdlm/errors/v2_test.loadConfig)",
-	//         "error": "service configuration could not be loaded"
+	//         "error": "service configuration could not be loaded: could not decode configuration data: could not read configuration file: read: end of input"
 	//     }
 	// ]
 }

format.go

@@ -120,18 +120,19 @@ func format(key int, nextE error, sp string, jsonData []map[string]interface{},
 				)
 			}
 		}
-		if "" != frameMessage(nextE) {
-			data["error"] = frameMessage(nextE)
+		if message := messageFor(nextE, flagTrace); "" != message {
+			data["error"] = message
 		}
 		jsonData = append(jsonData, data)
 
 	} else {
-		if "" != frameMessage(nextE) {
-			fmt.Fprintf(str, "%s%s", sp, frameMessage(nextE))
+		message := messageFor(nextE, flagTrace)
+		if "" != message {
+			fmt.Fprintf(str, "%s%s", sp, message)
 		}
 
 		if flagDetail || flagTrace {
-			if "" != frameMessage(nextE) {
+			if "" != message {
 				fmt.Fprintf(str, " - ")
 			}
 			if ok && nil != err.Caller() {
@@ -158,6 +159,26 @@ func format(key int, nextE error, sp string, jsonData []map[string]interface{},
 	return sp, jsonData, str
 }
 
+// messageFor chooses between the whole chain and this frame alone.
+//
+// The trace verbs (%+v) print one line per frame, so each line must carry only its own message or
+// every line repeats the tail below it. Every OTHER form renders a single string, and that string
+// has to be the full message -- the same thing Error() and %s produce.
+//
+// %v used to take the per-frame path and stop at the first frame, so it printed only the outermost
+// message and silently discarded the cause. It is the most-used verb for an error in Go and the one
+// most loggers call, so the effect was that a wrapped cause was recorded everywhere except where
+// anyone looked: err.Error() had it, %s had it, %v did not.
+func messageFor(err error, perFrame bool) string {
+	if perFrame {
+		return frameMessage(err)
+	}
+	if nil == err {
+		return ""
+	}
+	return err.Error()
+}
+
 // frameMessage is one link's own message. For an *E that is its frame message without the wrapped
 // chain -- Error() now includes the cause, and a trace that prints one line per frame would otherwise
 // repeat the whole tail on every line. Any other error type has only its own message to give.