QUIC transport does not support private networks, please dis

Error message

QUIC transport does not support private networks, please disable Swarm.Transports.Network.QUIC

What it means

The QUIC transport in go-libp2p cannot operate inside a libp2p private network (a swarm protected by a shared passphase via libp2p pnet). Kubo detects that both QUIC and a private network are enabled during transport setup and aborts startup, telling the user to disable QUIC in config because the combination is unsupported by the underlying library.

Source

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

		if wsEnabled {
			if params.ForgeMgr == nil {
				opts.Opts = append(opts.Opts, libp2p.Transport(websocket.New))
			} else {
				opts.Opts = append(opts.Opts, libp2p.Transport(websocket.New, websocket.WithTLSConfig(params.ForgeMgr.TLSConfig())))
			}
		}

		if tcpEnabled && wsEnabled && os.Getenv("LIBP2P_TCP_MUX") != "false" {
			if privateNetworkEnabled {
				log.Error("libp2p.ShareTCPListener() is not supported in private networks, please disable Swarm.Transports.Network.Websocket or run with LIBP2P_TCP_MUX=false to make this message go away")
			} else {
				opts.Opts = append(opts.Opts, libp2p.ShareTCPListener())
			}
		}

		if tptConfig.Network.QUIC.WithDefault(!privateNetworkEnabled) {
			if privateNetworkEnabled {
				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(

View on GitHub (pinned to 329838acdf)

Solutions

Disable QUIC for the private node: `ipfs config --json Swarm.Transports.Network.QUIC false`
Also disable WebTransport/WebRTCDirect if present (they are QUIC-based and fail the same way, see errors 593/594)
Verify TCP is enabled for connectivity: `ipfs config --json Swarm.Transports.Network.TCP`
Restart the daemon

Example fix

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

// after (with a private network / swarm key)
ipfs config --json Swarm.Transports.Network.QUIC false

Defensive patterns

Strategy: try-catch

Try / catch

if err := node.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "QUIC transport does not support private networks") {
        // fix config automatically or surface actionable guidance
        return fmt.Errorf("private network active: set Swarm.Transports.Network.QUIC=false: %w", err)
    }
    return err
}

When it happens

Trigger: Daemon startup with a private network enabled ( Swarm.Key / libp2p pnet active) while Swarm.Transports.Network.QUIC resolves to enabled — either explicitly set to true or defaulted on because the default is disabled only when privateNetworkEnabled; any explicit true triggers it.

Common situations: Clusters and private swarms (e.g. ipfs-cluster managed private networks) that upgraded from older kubo where QUIC defaulted differently, or operators who explicitly enabled QUIC while running with a protect/swarm key.

Related errors

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