jaegertracing/jaeger · error

unknown encoding type: %#02x

Error message

unknown encoding type: %#02x

What it means

createTraceKV serializes a span for writing to Badger according to the SpanWriter's configured encodingType. If the writer was constructed with an encoding byte that is neither protoEncoding nor jsonEncoding, marshalling cannot proceed and this error is returned. It indicates a programmer/configuration error in how the SpanWriter was created, since both branches are internal constants.

Source

Thrown at internal/storage/v1/badger/spanstore/writer.go:177

	key = make([]byte, 1+sizeOfTraceID+8+8)
	key[0] = spanKeyPrefix
	pos := 1
	binary.BigEndian.PutUint64(key[pos:], span.TraceID.High)
	pos += 8
	binary.BigEndian.PutUint64(key[pos:], span.TraceID.Low)
	pos += 8
	binary.BigEndian.PutUint64(key[pos:], startTime)
	pos += 8
	binary.BigEndian.PutUint64(key[pos:], uint64(span.SpanID))

	switch encodingType {
	case protoEncoding:
		bb, err = proto.Marshal(span)
	case jsonEncoding:
		bb, err = json.Marshal(span)
	default:
		return nil, nil, fmt.Errorf("unknown encoding type: %#02x", encodingType)
	}

	return key, bb, err
}

View on GitHub (pinned to 806f444784)

Solutions

1. Initialize the SpanWriter only with the supported encoding values (proto or json) from this package.
2. Search the codebase for where encodingType is assigned and fix the invalid value.
3. Add a validation at SpanWriter construction time to fail fast on unknown encodings.
4. Extend the switch in createTraceKV if a genuinely new encoding is being introduced.

Example fix

// before
w := &SpanWriter{encodingType: 0x07} // invalid
// after
w := NewSpanWriter(store, cache, protoEncoding, ...) // only proto/json encodings

func validEncoding(t byte) bool { return t == protoEncoding || t == jsonEncoding }
if !validEncoding(w.encodingType) { return errors.New("SpanWriter: unsupported encodingType") }

key, bb, err := createTraceKV(span, w.encodingType, startTime)
if err != nil {
    return nil, fmt.Errorf("span serialization failed: %w", err)
}

When it happens

Trigger: Constructing a SpanWriter with an unsupported encodingType byte and then writing spans (via createTraceEntry -> createTraceKV).

Common situations: Custom forks/embedding code passing an invalid encoding constant, or a refactor introducing a new encoding without updating this switch.

Related errors

• unknown encoding type: %#02x
• invalid version
• failed to obtain purger: %w
• unknown column for position: %q
• unsupported schema version: %v

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/3bad60ae4dbc6cd2. Report an issue: GitHub.