nats-io/nats-server · error

thw: encoded version not known

Error message

thw: encoded version not known

What it means

Binary decode of a timing-wheel snapshot: the version byte is not 1 (the only supported encoding version), so the buffer cannot be interpreted and decode aborts before reading any entries. The version byte of the encoded blob is the input at fault.

Source

Thrown at server/thw/thw.go:28

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package thw

import (
	"encoding/binary"
	"errors"
	"io"
	"math"
	"time"
)

// Error for when we can not locate a task for removal or updates.
var ErrTaskNotFound = errors.New("thw: task not found")

// Error for when we try to decode a binary-encoded THW with an unknown version number.
var ErrInvalidVersion = errors.New("thw: encoded version not known")

const (
	tickDuration = int64(time.Second) // Tick duration in nanoseconds.
	wheelBits    = 12                 // 2^12 = 4096 slots.
	wheelSize    = 1 << wheelBits     // Number of slots in the wheel.
	wheelMask    = wheelSize - 1      // Mask for calculating position.
	headerLen    = 17                 // 1 byte magic + 2x uint64s
)

// slot represents a single slot in the wheel.
type slot struct {
	entries map[uint64]int64 // Map of sequence to expires.
	lowest  int64            // Lowest expiration time in this slot.
}

// HashWheel represents the timing wheel.
type HashWheel struct {
	wheel  []*slot // Array of slots.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Re-encode the wheel snapshot using version 1
2. Regenerate the persisted state instead of decoding incompatible data
3. Extend the decoder if a newer encoding version was introduced

When it happens

Trigger: Thrown at server/thw/thw.go:28 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/cd941dbd671c4404. Report an issue: GitHub.