livekit/livekit · error

invalid router message

Error message

invalid router message

What it means

ErrInvalidRouterMessage is a sentinel error in pkg/routing indicating that a message received by the router does not conform to the expected router message format. The routing layer validates incoming messages before dispatching them to handlers, and any message that cannot be parsed or does not match the router's expected shape is rejected with this error. It signals a protocol/contract mismatch between sender and receiver.

Source

Thrown at pkg/routing/errors.go:28

// 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 routing

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. Verify the message is fully constructed and serialized with the expected protobuf type before publishing it to the router
2. Ensure all nodes run compatible LiveKit versions so message schemas match
3. Check that the message is being sent to the correct routing topic/handler
4. Log the offending message contents at the send site to find the field that is missing or invalid

Example fix

// before
router.Publish(ctx, nil)
// after
msg := &livekit.RouterMessage{ /* populate required fields */ }
if msg == nil || proto.Size(msg) == 0 {
    return errors.New("refusing to publish empty router message")
}
router.Publish(ctx, msg)

func validRouterMessage(msg *livekit.RouterMessage) bool {
    return msg != nil && proto.Size(msg) > 0
}
if !validRouterMessage(msg) {
    return errors.New("refusing to publish empty/invalid router message")
}

func isValidRouterMessage(m interface{}) bool {
    m, ok := m.(*livekit.RouterMessage)
    return ok && m != nil
}

When it happens

Trigger: Publishing or routing a message through the routing layer whose payload is nil, malformed, or lacks required fields expected by the router's message handler; sending an unregistered/unknown message type into the router.

Common situations: Version skew between LiveKit nodes where one node sends a message shape another doesn't understand; custom integrations hand-crafting router messages; serialization/deserialization bugs producing empty or partially populated messages.

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/6f30961fc59eca3d. Report an issue: GitHub.