jaegertracing/jaeger · error

unknown encoding type: %#02x

Error message

unknown encoding type: %#02x

What it means

decodeValue in the Badger span store reads the per-entry user metadata byte that records how a span was serialized (json or proto). If the byte is neither value, it cannot deserialize the span and returns this error. It almost always means the Badger database contains entries written by an incompatible/unknown encoder.

Source

Thrown at internal/storage/v1/badger/spanstore/reader.go:105

			reader.preloadOperations(service)
		}
	}
	return reader
}

func decodeValue(val []byte, encodeType byte) (*model.Span, error) {
	sp := model.Span{}
	switch encodeType {
	case jsonEncoding:
		if err := json.Unmarshal(val, &sp); err != nil {
			return nil, err
		}
	case protoEncoding:
		if err := sp.Unmarshal(val); err != nil {
			return nil, err
		}
	default:
		return nil, fmt.Errorf("unknown encoding type: %#02x", encodeType)
	}
	return &sp, nil
}

// getTraces enriches TraceIDs to Traces
func (r *TraceReader) getTraces(traceIDs []model.TraceID) ([]*model.Trace, error) {
	// Get by PK
	traces := make([]*model.Trace, 0, len(traceIDs))
	prefixes := make([][]byte, 0, len(traceIDs))

	for _, traceID := range traceIDs {
		prefixes = append(prefixes, createPrimaryKeySeekPrefix(traceID))
	}

	err := r.store.View(func(txn *badger.Txn) error {
		opts := badger.DefaultIteratorOptions
		it := txn.NewIterator(opts)
		defer it.Close()

View on GitHub (pinned to 806f444784)

Solutions

1. Check the hex value in the message and compare against the jsonEncoding/protoEncoding constants for the Jaeger version in use.
2. Upgrade or downgrade Jaeger so the store matches the version that wrote the data.
3. Do not manually edit Badger values; re-ingest the affected traces from the original source.
4. If the directory is foreign data, point Jaeger at the correct storage directory.

if e.UserMeta != jsonEncoding && e.UserMeta != protoEncoding {
    return fmt.Errorf("skipping entry with unknown encoding %#02x", e.UserMeta)
}

func knownEncoding(b byte) bool { return b == jsonEncoding || b == protoEncoding }
// caller: if !knownEncoding(encodeType) { skip/log instead of decodeValue }

span, err := decodeValue(val, encodeType)
if err != nil {
    logger.Warn("skipping unreadable span", zap.Error(err))
    continue
}

When it happens

Trigger: Reading a trace whose stored badger entry UserMeta byte is neither jsonEncoding nor protoEncoding — e.g. data written by a different Jaeger/Badger version or corrupted/foreign database files.

Common situations: Opening a Badger directory written by a newer or customized Jaeger version, hand-migrated key/value data, or bit-rot/corruption of entry metadata.

Related errors

• unknown encoding type: %#02x
• unknown column for position: %q
• trace not found
• trace not found
• trace not found

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