ipfs/kubo · error

running libp2p with Swarm.Transports.Multiplexers.Yamux disa

Error message

running libp2p with Swarm.Transports.Multiplexers.Yamux disabled is not supported

What it means

Yamux is the only stream multiplexer kubo still supports, and it must remain enabled so the node can interoperate with the rest of the IPFS network. Setting Swarm.Transports.Multiplexers.Yamux to a negative (disabled) value in the config makes the node unable to speak any multiplexed stream transport, so makeSmuxTransportOption refuses to start.

Source

Thrown at core/node/libp2p/smux.go:18

package libp2p

import (
	"errors"
	"os"

	"github.com/ipfs/kubo/config"

	"github.com/libp2p/go-libp2p"
	"github.com/libp2p/go-libp2p/p2p/muxer/yamux"
)

func makeSmuxTransportOption(tptConfig config.Transports) (libp2p.Option, error) {
	if prefs := os.Getenv("LIBP2P_MUX_PREFS"); prefs != "" {
		return nil, errors.New("configuring muxers with LIBP2P_MUX_PREFS is no longer supported, use Swarm.Transports.Multiplexers")
	}
	if tptConfig.Multiplexers.Yamux < 0 {
		return nil, errors.New("running libp2p with Swarm.Transports.Multiplexers.Yamux disabled is not supported")
	}

	return libp2p.Muxer(yamux.ID, yamux.DefaultTransport), nil
}

func SmuxTransport(tptConfig config.Transports) func() (opts Libp2pOpts, err error) {
	return func() (opts Libp2pOpts, err error) {
		res, err := makeSmuxTransportOption(tptConfig)
		if err != nil {
			return opts, err
		}
		opts.Opts = append(opts.Opts, res)
		return opts, nil
	}
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-enable yamux: `ipfs config --json Swarm.Transports.Multiplexers.Yamux 1`
2. Remove the whole override to restore defaults: `ipfs config --json Swarm.Transports.Multiplexers '{}'`
3. Restart the daemon

Example fix

// before
ipfs config --json Swarm.Transports.Multiplexers.Yamux -1

// after
ipfs config --json Swarm.Transports.Multiplexers.Yamux 1

// fail early on an unsupported yamux setting
val=$(ipfs config --json Swarm.Transports.Multiplexers.Yamux 2>/dev/null || echo 1)
if [ "$val" -lt 0 ]; then
  echo "error: Yamux cannot be disabled; set Swarm.Transports.Multiplexers.Yamux >= 0" >&2
  exit 1
fi

When it happens

Trigger: Daemon startup when `ipfs config --json Swarm.Transports.Multiplexers.Yamux` is set to a negative number (e.g. -1), i.e. explicitly disabling the yamux muxer.

Common situations: Copy-pasted config from outdated documentation or issue threads that suggested disabling yamux when mplex/quic muxers were being phased out; scripts that compute muxer flags arithmetically and produce -1 for 'off'.

Related errors

• configuring muxers with LIBP2P_MUX_PREFS is no longer suppor
• unrecognized Swarm.ConnMgr.Type: %q
• unknown pubsub router %s
• incorrectly formatted address filter in config: %s
• unrecognized reachability option: %s

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