cloudflare/cloudflared · warning

flow is already registered for this connection

Error message

flow is already registered for this connection

What it means

ErrSessionAlreadyRegistered is returned when the same RequestID is registered twice on the same connection. RegisterSession finds an existing session whose ConnectionID matches the incoming connection, so a second registration would duplicate socket binding and session state. It is an idempotency guard, not a fatal conflict like ErrSessionBoundToOtherConn.

Source

Thrown at quic/v3/manager.go:21

import (
	"errors"
	"sync"

	"github.com/rs/zerolog"

	"github.com/cloudflare/cloudflared/ingress"
	"github.com/cloudflare/cloudflared/management"

	cfdflow "github.com/cloudflare/cloudflared/flow"
)

var (
	// ErrSessionNotFound indicates that a session has not been registered yet for the request id.
	ErrSessionNotFound = errors.New("flow not found")
	// ErrSessionBoundToOtherConn is returned when a registration already exists for a different connection.
	ErrSessionBoundToOtherConn = errors.New("flow is in use by another connection")
	// ErrSessionAlreadyRegistered is returned when a registration already exists for this connection.
	ErrSessionAlreadyRegistered = errors.New("flow is already registered for this connection")
	// ErrSessionRegistrationRateLimited is returned when a registration fails due to rate limiting on the number of active flows.
	ErrSessionRegistrationRateLimited = errors.New("flow registration rate limited")
)

type SessionManager interface {
	// RegisterSession will register a new session if it does not already exist for the request ID.
	// During new session creation, the session will also bind the UDP socket for the origin.
	// If the session exists for a different connection, it will return [ErrSessionBoundToOtherConn].
	RegisterSession(request *UDPSessionRegistrationDatagram, conn DatagramConn) (Session, error)
	// GetSession returns an active session if available for the provided connection.
	// If the session does not exist, it will return [ErrSessionNotFound]. If the session exists for a different
	// connection, it will return [ErrSessionBoundToOtherConn].
	GetSession(requestID RequestID) (Session, error)
	// UnregisterSession will remove a session from the current session manager. It will attempt to close the session
	// before removal.
	UnregisterSession(requestID RequestID)
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Treat the existing session as success: on this error, look up the session with GetSession and continue using it instead of failing
2. Make registration idempotent on the client by tracking which RequestIDs have already been registered per connection
3. Delay retransmission of registration datagrams or deduplicate them at the send layer

Example fix

// before
_, err := manager.RegisterSession(&request, eyeball)
if err != nil {
    return err // fails on benign duplicate
}
// after
session, err := manager.RegisterSession(&request, eyeball)
if errors.Is(err, v3.ErrSessionAlreadyRegistered) {
    session, err = manager.GetSession(request.RequestID) // reuse existing
    if err != nil {
        return err
    }
} else if err != nil {
    return err
}

// track registrations locally
if _, seen := registered[id]; seen {
    return existingSession(id), nil
}

session, err := manager.RegisterSession(&request, eyeball)
if errors.Is(err, v3.ErrSessionAlreadyRegistered) {
    session, err = manager.GetSession(request.RequestID)
}

When it happens

Trigger: Calling manager.RegisterSession twice with the same request and the same underlying connection (conn.ID() == session.ConnectionID()); re-sending a registration datagram whose response was lost.

Common situations: Registration retransmit after response packet loss; client retry logic that doesn't deduplicate; tests intentionally double-registering.

Related errors

• flow not found
• flow is in use by another connection
• flow registration rate limited
• flow was closed directly
• invalid datagram type expected

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/53170ddb63f3defd. Report an issue: GitHub.