configuring muxers with LIBP2P_MUX_PREFS is no longer suppor

Error message

configuring muxers with LIBP2P_MUX_PREFS is no longer supported, use Swarm.Transports.Multiplexers

What it means

Kubo no longer reads the LIBP2P_MUX_PREFS environment variable to select stream multiplexers; muxer selection moved to the Swarm.Transports.Multiplexers config section. At daemon startup, makeSmuxTransportOption checks for this legacy env var and refuses to continue so stale environment configuration is not silently ignored. The user must migrate the muxer preference into the config file.

Source

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

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

Remove LIBP2P_MUX_PREFS from the environment (unset in shell, systemd unit, Dockerfile/entrypoint, etc.)
If a specific muxer is needed, configure it via `ipfs config --json Swarm.Transports.Multiplexers.Yamux 1` (yamux is the only supported muxer here; it cannot be disabled, see error 591)
Restart the daemon and verify with `ipfs config Swarm.Transports.Multiplexers`

Example fix

# before (systemd unit / docker entrypoint)
Environment=LIBP2P_MUX_PREFS=mplex
ipfs daemon

# after
# remove the env line, then:
ipfs config --json Swarm.Transports.Multiplexers '{"Yamux": 1}'
ipfs daemon

Defensive patterns

Strategy: validation

Validate before calling

// before starting the daemon
if [ -n "$LIBP2P_MUX_PREFS" ]; then
  echo "error: LIBP2P_MUX_PREFS is no longer supported; use Swarm.Transports.Multiplexers" >&2
  exit 1
fi
ipfs daemon

Prevention

Audit systemd units, Dockerfiles and shell profiles for legacy LIBP2P_* env vars before upgrading kubo
Prefer Swarm.Transports.* config keys over libp2p environment variables
Pin muxer settings in the repo-backed config instead of the environment

When it happens

Trigger: Starting the kubo daemon (ipfs daemon) with the LIBP2P_MUX_PREFS environment variable set to a non-empty value; makeSmuxTransportOption returns this error before building libp2p options.

Common situations: Environments that predate the config-based muxer selection (pre go-libp2p 0.22 / kubo 0.20 era) and carried the env var forward in systemd units, Docker images, or shell profiles; upgrading an old node whose startup scripts still export LIBP2P_MUX_PREFS=mplex.

Related errors

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