nats-io/nats-server · error

thw: task not found

Error message

thw: task not found

What it means

Timing-wheel Update/Remove: no task exists at the indicated wheel slot/sequence — it already fired and was removed, or the seq is wrong. The lookup guard returns ErrTaskNotFound instead of mutating an empty slot.

Source

Thrown at server/thw/thw.go:25

//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// 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.
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Treat removal of an already-fired task as success (idempotent)
2. Verify the task seq and wheel position before removal
3. Guard against concurrent removal of the same task

When it happens

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