Why might encoding/json silently skip your MarshalText or UnmarshalText methods?

## Why it is silent `encoding/json` decides how to encode a type once, by asking whether it implements the marshaler interfaces. If it does not, that is not an error — it is the normal case, and json encodes the type structurally. So the failure mode of a mis-declared marshaler is never a compile error and never a runtime error. It is output that looks like the type never had a method at all: a struct comes out as a JSON object of its fields, a named integer comes out as a number. ## Method sets, briefly The method set of `T` contains the methods declared with receiver `T`. The method set of `*T` contains the methods declared with receiver `T` **and** those declared with receiver `*T`. Interface satisfaction is checked against the method set, so: - `MarshalText` on `func (v T)` → both `T` and `*T` satisfy `encoding.TextMarshaler`. - `MarshalText` on `func (v *T)` → only `*T` satisfies it. That asymmetry is the whole bug. ## The marshal side: addressability When json is encoding a value of type `T` and finds that only `*T` implements the interface, it will use the pointer method **if the value it is holding is addressable** — that is, if it can legally take `&value`. It does this through reflection, and reflection is strict about it. `json.Marshal(v)` receives an `any` holding a copy of `v`. A value inside an interface is not addressable, so neither it nor any of its fields can have their addresses taken, and pointer-receiver marshalers on the top-level value and its direct fields are skipped. `json.Marshal(&v)` puts a pointer in the interface; json dereferences it and now everything reachable through that pointer is addressable, and the same methods fire. The visible symptom is a type that serialises correctly in one call site and structurally in another, or a value that has the right form in the response body but the wrong form when the same struct is logged. Other unaddressable positions behave the same way: a value stored in a map (`m[k]` is not addressable) and a value returned directly from a function call. The fix is not to remember which call site passes a pointer. It is to declare `MarshalText` on the value receiver, where it belongs — it only reads the receiver, so there is no reason for it to be a pointer method, and a value receiver makes both `T` and `*T` work everywhere. ## The unmarshal side: a write into a copy The mirror mistake goes the other way and is worse, because the method actually runs. ```go func (d Duration) UnmarshalText(text []byte) error { // wrong receiver v, err := time.ParseDuration(string(text)) if err != nil { return err } d = Duration(v) // assigns to the copy; discarded on return return nil } ``` This compiles. `*Duration` satisfies `encoding.TextUnmarshaler`, because value-receiver methods are in the pointer's method set, so json finds the interface and calls the method. The method parses correctly, returns `nil`, and json moves on satisfied. The field is left holding the zero value. There is no error to log, no panic, no vet warning at the call site. A config loader built this way starts every timeout at zero and the service dies of instant deadline expiry in production with a perfectly clean startup log. A related silent case: if the type implements neither interface, json decodes structurally, so a JSON string decoded into a named integer type yields a type error — but a JSON object decoded into a struct that expected a text form quietly fills whatever fields happen to match and leaves the rest zero. ## Finding it The diagnostic that catches every variant at once is a table-driven round-trip property test in the package that owns the type: 1. A table of interesting values: the zero value, each named constant, boundary values, a value that needs escaping, a negative value. 2. For each, `json.Marshal` the value, `json.Unmarshal` into a fresh variable, compare for exact equality. 3. Assert the intermediate bytes too, at least for one case, so a marshaler that is being skipped shows up as `{"R":1}` instead of `"eu"` rather than passing because both directions are equally broken. That third point matters more than it looks. A round-trip test alone can pass while both methods are being ignored, because structural encoding round-trips fine — it is just the wrong wire format. Asserting the bytes for one golden case is what distinguishes "round-trips" from "round-trips in the format we published". Run the test with the value **and** with a pointer to it, since those are different code paths, and include a case where the value sits inside a map and inside a slice. ## The rule to carry away Declare `MarshalText` on the value receiver and `UnmarshalText` on the pointer receiver, keep the whole method set of a type consistent about receivers, and let a golden-byte round-trip test in the owning package prove the methods are actually being called.