{"record":{"id":"1ee608547ac01065","repo":"ipfs/kubo","slug":"quic-transport-does-not-support-private-networks","errorCode":null,"errorMessage":"QUIC transport does not support private networks, please disable Swarm.Transports.Network.QUIC","messagePattern":"QUIC transport does not support private networks, please disable Swarm\\.Transports\\.Network\\.QUIC","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/node/libp2p/transport.go","lineNumber":54,"sourceCode":"\t\tif wsEnabled {\n\t\t\tif params.ForgeMgr == nil {\n\t\t\t\topts.Opts = append(opts.Opts, libp2p.Transport(websocket.New))\n\t\t\t} else {\n\t\t\t\topts.Opts = append(opts.Opts, libp2p.Transport(websocket.New, websocket.WithTLSConfig(params.ForgeMgr.TLSConfig())))\n\t\t\t}\n\t\t}\n\n\t\tif tcpEnabled && wsEnabled && os.Getenv(\"LIBP2P_TCP_MUX\") != \"false\" {\n\t\t\tif privateNetworkEnabled {\n\t\t\t\tlog.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\")\n\t\t\t} else {\n\t\t\t\topts.Opts = append(opts.Opts, libp2p.ShareTCPListener())\n\t\t\t}\n\t\t}\n\n\t\tif tptConfig.Network.QUIC.WithDefault(!privateNetworkEnabled) {\n\t\t\tif privateNetworkEnabled {\n\t\t\t\treturn opts, fmt.Errorf(\n\t\t\t\t\t\"QUIC transport does not support private networks, please disable Swarm.Transports.Network.QUIC\",\n\t\t\t\t)\n\t\t\t}\n\t\t\topts.Opts = append(opts.Opts, libp2p.Transport(quic.NewTransport))\n\t\t}\n\n\t\tif tptConfig.Network.WebTransport.WithDefault(!privateNetworkEnabled) {\n\t\t\tif privateNetworkEnabled {\n\t\t\t\treturn opts, fmt.Errorf(\n\t\t\t\t\t\"WebTransport transport does not support private networks, please disable Swarm.Transports.Network.WebTransport\",\n\t\t\t\t)\n\t\t\t}\n\t\t\topts.Opts = append(opts.Opts, libp2p.Transport(webtransport.New))\n\t\t}\n\n\t\tif tptConfig.Network.WebRTCDirect.WithDefault(!privateNetworkEnabled) {\n\t\t\tif privateNetworkEnabled {\n\t\t\t\treturn opts, fmt.Errorf(","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/node/libp2p/transport.go#L36-L72","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nipfs config --json Swarm.Transports.Network.QUIC true\n\n// after (with a private network / swarm key)\nipfs config --json Swarm.Transports.Network.QUIC false","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := node.Start(ctx); err != nil {\n    if strings.Contains(err.Error(), \"QUIC transport does not support private networks\") {\n        // fix config automatically or surface actionable guidance\n        return fmt.Errorf(\"private network active: set Swarm.Transports.Network.QUIC=false: %w\", err)\n    }\n    return err\n}","preventionTips":[],"tags":["libp2p","quic","private-network","transport"],"backgroundTag":"transport-incompatible-with-private-network","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}