What causes "webrtc connection not found" in m1k1o/neko?

Re-create the peer via the WebRTC manager (CreatePeer) and redo signaling.

m1k1o/neko · error · ErrWebRTCConnectionNotFound

webrtc connection not found

Error message

webrtc connection not found

What it means

ErrWebRTCConnectionNotFound is a sentinel error in the neko types package indicating that a WebRTC peer/connection lookup failed — no peer connection exists for the referenced session or identifier. It is returned when code tries to interact with (pause, video/audio config, signaling on) a peer that is not registered.

Source

Thrown at server/pkg/types/webrtc.go:11

package types

import (
	"errors"

	"github.com/pion/webrtc/v4"
)

var (
	ErrWebRTCDataChannelNotFound = errors.New("webrtc data channel not found")
	ErrWebRTCConnectionNotFound  = errors.New("webrtc connection not found")
	ErrWebRTCStreamNotFound      = errors.New("webrtc stream not found")
)

type ICEServer struct {
	URLs       []string `mapstructure:"urls"       json:"urls"`
	Username   string   `mapstructure:"username"   json:"username,omitempty"`
	Credential string   `mapstructure:"credential" json:"credential,omitempty"`
}

type PeerVideo struct {
	Disabled bool   `json:"disabled"`
	ID       string `json:"id"`
	Video    string `json:"video"` // TODO: Remove this, used for compatibility with old clients.
	Auto     bool   `json:"auto"`
}

type PeerVideoRequest struct {
	Disabled *bool           `json:"disabled,omitempty"`

View on GitHub (pinned to b0f01cedea)

Solutions

Re-create the peer via the WebRTC manager (CreatePeer) and redo signaling.
Ignore/drop stale signaling messages for destroyed peers instead of failing.
Check client logs for premature disconnects and network/ICE problems.
Ensure the session is connected before requesting media operations.
Upgrade/check versions — some flows changed around pion/webrtc v4 migration.

Example fix

// before
peer.SetPaused(false) // may return ErrWebRTCConnectionNotFound
// after
if peer == nil || peer.Connection() == nil {
    return types.ErrWebRTCConnectionNotFound // caller recreates the peer
}
peer.SetPaused(false)

Defensive patterns

Strategy: validation

Validate before calling

// ensure the session has a live peer before media operations
peer := session.GetWebRTCPeer()
if peer == nil {
    return errors.New("no active webrtc peer for session")
}

Type guard

func HasPeer(s types.Session) bool { return s.GetWebRTCPeer() != nil }

Try / catch

if err := peer.SetPaused(false); err != nil {
    if errors.Is(err, types.ErrWebRTCConnectionNotFound) {
        // peer gone: trigger client reconnect/re-signaling
        return
    }
    return err
}

Prevention

Drop signaling messages for destroyed peers gracefully.
Recreate peers instead of reusing stale references after reconnect.
Monitor disconnect events to clean peer maps promptly.
Test against flaky networks to catch destroy races.

When it happens

Trigger: Operations on a WebRTCPeer (SetPaused, SetVideo, CreateOffer, candidates) whose underlying *webrtc.PeerConnection is nil or already destroyed; referencing a peer by session after the session disconnected.

Common situations: Delayed signaling messages arriving after the peer was destroyed (tab close, network drop); server-side cleanup racing client requests; session re-created so old peer references are invalid.

Related errors

AI-assisted analysis of m1k1o/neko@b0f01cedea (2026-09-01). Data as JSON: /api/errors/ead364db5dd66325. Report an issue: GitHub.