WebTransport transport does not support private networks, pl

Error message

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

What it means

WebTransport is built on QUIC, so it inherits QUIC's incompatibility with libp2p private networks (pnet). Kubo's transport setup detects a private network with WebTransport enabled and refuses to start rather than listening on a transport that cannot work.

Source

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

			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(
					"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
	}
}

View on GitHub (pinned to 329838acdf)

Solutions

Disable it: `ipfs config --json Swarm.Transports.Network.WebTransport false`
Also disable QUIC and WebRTCDirect (errors 592/594) since all three fail with pnet
Ensure Swarm.Transports.Network.TCP is enabled so the node still listens
Restart the daemon

Example fix

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

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

Defensive patterns

Strategy: try-catch

Try / catch

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

When it happens

Trigger: Daemon startup when Swarm.Transports.Network.WebTransport is explicitly true while a private network (swarm key) is active; the WithDefault(!privateNetworkEnabled) default would turn it off, so an explicit enable is required to hit this.

Common situations: Operators running private/protected swarms who copied public-node configs enabling WebTransport, or who set all transports to true wholesale while using a swarm key.

Related errors

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