ipfs/kubo · error

failed to enable Swarm.EnableHolePunching: it requires Swarm

Error message

failed to enable Swarm.EnableHolePunching: it requires Swarm.RelayClient.Enabled to be true

What it means

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.

Source

Thrown at core/node/libp2p/relay.go:116

						}()
						return r
					},
					autorelay.WithMinInterval(0),
				))
			return
		}),
		autoRelayFeeder(cfgPeering, peerChan),
	)
}

func HolePunching(flag config.Flag, hasRelayClient bool) func() (opts Libp2pOpts, err error) {
	return func() (opts Libp2pOpts, err error) {
		if flag.WithDefault(true) {
			if !hasRelayClient {
				// If hole punching is explicitly enabled but the relay client is disabled,
				// return an error; otherwise just silently disable hole punching.
				if flag != config.Default {
					err = fmt.Errorf("failed to enable Swarm.EnableHolePunching: it requires Swarm.RelayClient.Enabled to be true")
				} else {
					log.Info("HolePunching has been disabled due to the RelayClient being disabled.")
				}
				return
			}
			opts.Opts = append(opts.Opts, libp2p.EnableHolePunching())
		}
		return
	}
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Set Swarm.RelayClient.Enabled=true so hole punching has relayed connections to upgrade
2. Or remove the explicit Swarm.EnableHolePunching=true to let it default (and auto-disable without a relay client)
3. Reference: docs/config.md for Swarm.EnableHolePunching and Swarm.RelayClient

When it happens

Trigger: Thrown at core/node/libp2p/relay.go:116 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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