nats-io/nats-server · error

unknown trace type %v

Error message

unknown trace type %v

What it means

Raised in MsgTraceEvents.UnmarshalJSON: a trace event's "type" field does not map to any entry in the msgTraceInterfaces registry (MsgTraceJetStreamType, MsgTraceEgressType, etc.), so the decoder cannot pick a concrete trace type to unmarshal into. Typically means the JSON was produced by a newer/older server with unknown trace types.

Source

Thrown at server/msgtrace.go:175

	MsgTraceJetStreamType:      MsgTraceJetStream{},
	MsgTraceEgressType:         MsgTraceEgress{},
}

func (t *MsgTraceEvents) UnmarshalJSON(data []byte) error {
	var raw []json.RawMessage
	err := json.Unmarshal(data, &raw)
	if err != nil {
		return err
	}
	*t = make(MsgTraceEvents, len(raw))
	var tt MsgTraceBase
	for i, r := range raw {
		if err = json.Unmarshal(r, &tt); err != nil {
			return err
		}
		tr, ok := msgTraceInterfaces[tt.Type]
		if !ok {
			return fmt.Errorf("unknown trace type %v", tt.Type)
		}
		te := tr.new()
		if err := json.Unmarshal(r, te); err != nil {
			return err
		}
		(*t)[i] = te
	}
	return nil
}

func getTraceAs[T MsgTrace](e any) *T {
	v, ok := e.(*T)
	if ok {
		return v
	}
	return nil
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Ensure the producer and consumer of the trace JSON run compatible server versions
2. Ignore/skip unknown trace types if forward compatibility is required

When it happens

Trigger: Thrown at server/msgtrace.go:175 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/d6e8e9ad6161e956. Report an issue: GitHub.