livekit/livekit · error

track not bound

Error message

track not bound

What it means

ErrTrackNotBound indicates that a MediaTrackSubscription never completed binding the subscribed track to the subscriber's receiver within the subscription timeout. In pkg/rtc/subscriptionmanager.go:584-585, after wait exceeds subscriptionTimeout, the manager logs "track not bound after timeout", records it with telemetry, and reports it via OnSubscriptionError. It signals the negotiation/subscription handshake did not finish in time.

Source

Thrown at pkg/rtc/errors.go:40

	ErrRoomClosed               = errors.New("room has already closed")
	ErrParticipantSessionClosed = errors.New("participant session is already closed")
	ErrPermissionDenied         = errors.New("no permissions to access the room")
	ErrMaxParticipantsExceeded  = errors.New("room has exceeded its max participants")
	ErrLimitExceeded            = errors.New("node has exceeded its configured limit")
	ErrAlreadyJoined            = errors.New("a participant with the same identity is already in the room")
	ErrDataChannelUnavailable   = errors.New("data channel is not available")
	ErrDataChannelBufferFull    = errors.New("data channel buffer is full")
	ErrTransportFailure         = errors.New("transport failure")
	ErrEmptyIdentity            = errors.New("participant identity cannot be empty")
	ErrEmptyParticipantID       = errors.New("participant ID cannot be empty")
	ErrMissingGrants            = errors.New("VideoGrant is missing")
	ErrInternalError            = errors.New("internal error")

	// Track subscription related
	ErrNoTrackPermission         = errors.New("participant is not allowed to subscribe to this track")
	ErrNoSubscribePermission     = errors.New("participant is not given permission to subscribe to tracks")
	ErrTrackNotFound             = errors.New("track cannot be found")
	ErrTrackNotBound             = errors.New("track not bound")
	ErrSubscriptionLimitExceeded = errors.New("participant has exceeded its subscription limit")

	ErrNoSubscribeMetricsPermission = errors.New("participant is not given permission to subscribe to metrics")
)

View on GitHub (pinned to ee45c3f0b1)

Solutions

1. Verify the subscriber's peer connection completed negotiation; restart the connection if ICE/negotiation is stalled.
2. Check server logs around the timeout for negotiation failures or pauses.
3. Retry the subscription (re-subscribe to the track) once the connection is healthy.

if errors.Is(err, rtc.ErrTrackNotBound) {
    logger.Warnw("subscription bind timed out", err)
    resubscribe(trackSID) // after confirming connection health
}

When it happens

Trigger: Returned by reconcileSubscription; raised as a timeout in the subscription manager when the track's bind step (SDP/negotiation completing for the subscriber) does not happen before subscriptionTimeout elapses.

Common situations: Slow or stalled peer connection negotiation under poor network conditions; subscriber pause/negotiation storms with many tracks; a subscriber connection that went stale after resume.

Related errors

• participant is not allowed to subscribe to this track
• participant is not given permission to subscribe to tracks
• track cannot be found
• participant has exceeded its subscription limit
• track is not open

AI-assisted analysis of livekit/livekit@ee45c3f0b1 (2026-09-02). Data as JSON: /api/errors/77225ffa67f068b9. Report an issue: GitHub.