livekit/livekit · error

participant identity cannot be empty

Error message

participant identity cannot be empty

What it means

ErrEmptyIdentity is a validation error from NewParticipant: the ParticipantParams.Identity field is an empty string. LiveKit requires every participant to have a non-empty identity, which is used as its unique user-facing key within a room, so construction is rejected immediately.

Source

Thrown at pkg/rtc/errors.go:31

// limitations under the License.

package rtc

import (
	"errors"
)

var (
	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. Ensure the join token includes a non-empty identity claim when minting it (AccessToken.SetIdentity).
2. Validate identity at your API edge (webhook/auth handler) before issuing tokens or creating participants.
3. Add a guard/log where ParticipantParams is built to catch upstream callers passing empty identity.
4. If identity is legitimately optional in your product, generate a stable server-side ID (e.g. UUID) as identity.

Example fix

// before
token.AddGrant(&auth.VideoGrant{RoomJoin: true, Room: room})
// after
token.SetIdentity(userID) // must be non-empty
if userID == "" {
    return errors.New("identity required to join room")
}

if identity == "" {
    return fmt.Errorf("cannot join room: identity is required")
}

func hasIdentity(params rtc.ParticipantParams) bool {
    return params.Identity != ""
}

p, err := rtc.NewParticipant(params)
if errors.Is(err, rtc.ErrEmptyIdentity) {
    // reject join request; log token/request that omitted identity
}

When it happens

Trigger: Calling rtc.NewParticipant with ParticipantParams.Identity == "" (pkg/rtc/participant.go:365), typically when the identity propagated from the join/SignalReceiver request or token grants is missing.

Common situations: A client joining with a token minted without the identity claim; upstream service passing an empty user ID into token creation; migration or refactoring dropping the identity assignment before calling NewParticipant.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• participant ID cannot be empty
• unknown job type
• invalid match expression result
• a participant with the same identity is already in the room
• unimplemented worker signal

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