cloudflare/cloudflared · error

flow is in use by another connection

Error message

flow is in use by another connection

What it means

ErrSessionBoundToOtherConn is returned when a registration already exists for the same RequestID but is bound to a different QUIC connection. QUICv3 datagram sessions are per-connection: migrating a flow to a new connection requires explicit migration handling, and silent re-binding would split the flow. The manager returns this error instead of overwriting the existing binding.

Source

Thrown at quic/v3/manager.go:19

package v3

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. Generate a fresh unique RequestID for each new connection instead of reusing the previous one
2. Use the library's session migration flow (handleSessionRegistrationDatagram / migration path) rather than plain re-registration
3. Tear down the old session (UnregisterSession) before registering on the new connection
4. Handle errors.Is(err, v3.ErrSessionBoundToOtherConn) on the client by restarting the flow with a new ID

Example fix

// before
// client reconnect reused old requestID
_, err := manager.RegisterSession(&request, newEyeball) // -> ErrSessionBoundToOtherConn
// after
request.RequestID = newRequestID() // unique per connection
_, err := manager.RegisterSession(&request, newEyeball)

// client side: guarantee uniqueness before registering
requestID, err := cfdRequestID.New() // fresh ID per connection

if _, err := manager.RegisterSession(&request, eyeball); errors.Is(err, v3.ErrSessionBoundToOtherConn) {
    // flow lives on another connection: start a new flow with a new RequestID
    return
}

When it happens

Trigger: Calling manager.RegisterSession(&request, eyeball) where s.sessions[request.RequestID] exists with session.ConnectionID() != conn.ID(). Also produced when handleSessionRegistrationDatagram receives a re-registration from a new connection without migration.

Common situations: Client reconnects after a network change and tries to register the same RequestID over a new QUIC connection; load-balancer shifting the client to a different edge connection; client bug reusing an old RequestID.

Related errors

• flow not found
• flow is already registered for this connection
• flow registration rate limited
• flow was closed directly
• failed to open a registration control stream: %w

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