WebRTC Direct transport does not support private networks, p

Error message

WebRTC Direct transport does not support private networks, please disable Swarm.Transports.Network.WebRTCDirect

What it means

WebRTC Direct is another QUIC-based transport and cannot run inside a libp2p private network. Kubo validates the transport configuration at startup and fails fast when WebRTCDirect is enabled together with a private network, since go-libp2p does not support that combination.

Source

Thrown at core/node/libp2p/transport.go:72

				return opts, fmt.Errorf(
					"QUIC transport does not support private networks, please disable Swarm.Transports.Network.QUIC",
				)
			}
			opts.Opts = append(opts.Opts, libp2p.Transport(quic.NewTransport))
		}

		if tptConfig.Network.WebTransport.WithDefault(!privateNetworkEnabled) {
			if privateNetworkEnabled {
				return opts, fmt.Errorf(
					"WebTransport transport does not support private networks, please disable Swarm.Transports.Network.WebTransport",
				)
			}
			opts.Opts = append(opts.Opts, libp2p.Transport(webtransport.New))
		}

		if tptConfig.Network.WebRTCDirect.WithDefault(!privateNetworkEnabled) {
			if privateNetworkEnabled {
				return opts, fmt.Errorf(
					"WebRTC Direct transport does not support private networks, please disable Swarm.Transports.Network.WebRTCDirect",
				)
			}
			opts.Opts = append(opts.Opts, libp2p.Transport(webrtc.New))
		}

		return opts, nil
	}
}

func BandwidthCounter() (opts Libp2pOpts, reporter *metrics.BandwidthCounter) {
	reporter = metrics.NewBandwidthCounter()
	opts.Opts = append(opts.Opts, libp2p.BandwidthReporter(reporter))
	return opts, reporter
}

View on GitHub (pinned to 329838acdf)

Solutions

Disable it: `ipfs config --json Swarm.Transports.Network.WebRTCDirect false`
Disable the other QUIC-family transports too (QUIC, WebTransport) to clear errors 592/593
Keep TCP enabled as the transport for the private swarm
Restart the daemon

Example fix

// before
ipfs config --json Swarm.Transports.Network.WebRTCDirect true

// after (private network)
ipfs config --json Swarm.Transports.Network.WebRTCDirect false

Defensive patterns

Strategy: try-catch

Try / catch

if err := node.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "WebRTC Direct transport does not support private networks") {
        return fmt.Errorf("private network active: set Swarm.Transports.Network.WebRTCDirect=false: %w", err)
    }
    return err
}

When it happens

Trigger: Daemon startup with Swarm.Transports.Network.WebRTCDirect explicitly enabled (true) while a private network (pnet swarm key) is active; the default would disable it in that case, so only an explicit enable triggers the error.

Common situations: Private swarm operators enabling every transport in config to maximize connectivity without realizing QUIC-family transports exclude private networks.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/48667e655f18c3b5. Report an issue: GitHub.