livekit/livekit · error

could not migrate participant

Error message

could not migrate participant

What it means

ErrCouldNotMigrateParticipant is a sentinel in pkg/routing returned when a participant cannot be migrated from one node to another. Migration requires state transfer (offer/answer, tracks, ICE state) between the source and destination nodes; any failure in that handoff surfaces as this error. It groups underlying causes under a single well-known error for callers.

Source

Thrown at pkg/routing/errors.go:34

import (
	"errors"
)

var (
	ErrNotFound             = errors.New("could not find object")
	ErrIPNotSet             = errors.New("ip address is required and not set")
	ErrHandlerNotDefined    = errors.New("handler not defined")
	ErrIncorrectRTCNode     = errors.New("current node isn't the RTC node for the room")
	ErrNodeNotFound         = errors.New("could not locate the node")
	ErrNodeLimitReached     = errors.New("reached configured limit for node")
	ErrInvalidRouterMessage = errors.New("invalid router message")
	ErrChannelClosed        = errors.New("channel closed")
	ErrChannelFull          = errors.New("channel is full")

	// errors when starting signal connection
	ErrRequestChannelClosed       = errors.New("request channel closed")
	ErrCouldNotMigrateParticipant = errors.New("could not migrate participant")
	ErrClientInfoNotSet           = errors.New("client info not set")
)

View on GitHub (pinned to ee45c3f0b1)

Solutions

1. Allow the client to reconnect — most clients transparently rejoin and the session is re-established on the new node
2. Verify source and destination nodes run compatible LiveKit versions
3. Check network connectivity and psrpc health between the two nodes
4. Retry migration to a different target node, or defer drain until participants naturally leave

// pre-check target node reachability before attempting migration
if err := pingNode(targetNode); err != nil {
    return fmt.Errorf("target node %s unreachable, pick another: %w", targetNode.Id, err)
}

if errors.Is(err, routing.ErrCouldNotMigrateParticipant) {
    logger.Warnw("migration failed, falling back to client reconnect", "error", err)
    return allowClientReconnect(participant)
}

When it happens

Trigger: Calling the participant migration path (during node drain or room rebalancing) when the target node cannot accept the participant, the source state cannot be serialized, or the handoff RPC fails.

Common situations: Node drain/maintenance while participants are connected; target node lost connectivity mid-migration; version mismatch between source and target nodes preventing state transfer; ICE/DTLS state already too far along to resume on another node.

Related errors

• could not find object
• ip address is required and not set
• handler not defined
• current node isn't the RTC node for the room
• could not locate the node

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