{"record":{"id":"4adb59dffdbeaa1f","repo":"ipfs/kubo","slug":"failed-to-enable-swarm-enableholepunching-it-requ","errorCode":null,"errorMessage":"failed to enable Swarm.EnableHolePunching: it requires Swarm.RelayClient.Enabled to be true","messagePattern":"failed to enable Swarm\\.EnableHolePunching: it requires Swarm\\.RelayClient\\.Enabled to be true","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/node/libp2p/relay.go","lineNumber":116,"sourceCode":"\t\t\t\t\t\t}()\n\t\t\t\t\t\treturn r\n\t\t\t\t\t},\n\t\t\t\t\tautorelay.WithMinInterval(0),\n\t\t\t\t))\n\t\t\treturn\n\t\t}),\n\t\tautoRelayFeeder(cfgPeering, peerChan),\n\t)\n}\n\nfunc HolePunching(flag config.Flag, hasRelayClient bool) func() (opts Libp2pOpts, err error) {\n\treturn func() (opts Libp2pOpts, err error) {\n\t\tif flag.WithDefault(true) {\n\t\t\tif !hasRelayClient {\n\t\t\t\t// If hole punching is explicitly enabled but the relay client is disabled,\n\t\t\t\t// return an error; otherwise just silently disable hole punching.\n\t\t\t\tif flag != config.Default {\n\t\t\t\t\terr = fmt.Errorf(\"failed to enable Swarm.EnableHolePunching: it requires Swarm.RelayClient.Enabled to be true\")\n\t\t\t\t} else {\n\t\t\t\t\tlog.Info(\"HolePunching has been disabled due to the RelayClient being disabled.\")\n\t\t\t\t}\n\t\t\t\treturn\n\t\t\t}\n\t\t\topts.Opts = append(opts.Opts, libp2p.EnableHolePunching())\n\t\t}\n\t\treturn\n\t}\n}\n","sourceCodeStart":98,"sourceCodeEnd":127,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/node/libp2p/relay.go#L98-L127","documentation":"Startup-time dependency check: Swarm.EnableHolePunching was explicitly set to true in the config, but Swarm.RelayClient.Enabled is false. Hole punching (DIRECT connections through relayed connections) only works when the relay client is active. If hole punching were left at its default, it would just be silently disabled instead.","triggerScenarios":"Thrown at core/node/libp2p/relay.go:116 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Set Swarm.RelayClient.Enabled=true so hole punching has relayed connections to upgrade","Or remove the explicit Swarm.EnableHolePunching=true to let it default (and auto-disable without a relay client)","Reference: docs/config.md for Swarm.EnableHolePunching and Swarm.RelayClient"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}