{"record":{"id":"b74a5d68dd465b5d","repo":"ipfs/kubo","slug":"configuring-muxers-with-libp2p-mux-prefs-is-no-lon","errorCode":null,"errorMessage":"configuring muxers with LIBP2P_MUX_PREFS is no longer supported, use Swarm.Transports.Multiplexers","messagePattern":"configuring muxers with LIBP2P_MUX_PREFS is no longer supported, use Swarm\\.Transports\\.Multiplexers","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/node/libp2p/smux.go","lineNumber":15,"sourceCode":"package libp2p\n\nimport (\n\t\"errors\"\n\t\"os\"\n\n\t\"github.com/ipfs/kubo/config\"\n\n\t\"github.com/libp2p/go-libp2p\"\n\t\"github.com/libp2p/go-libp2p/p2p/muxer/yamux\"\n)\n\nfunc makeSmuxTransportOption(tptConfig config.Transports) (libp2p.Option, error) {\n\tif prefs := os.Getenv(\"LIBP2P_MUX_PREFS\"); prefs != \"\" {\n\t\treturn nil, errors.New(\"configuring muxers with LIBP2P_MUX_PREFS is no longer supported, use Swarm.Transports.Multiplexers\")\n\t}\n\tif tptConfig.Multiplexers.Yamux < 0 {\n\t\treturn nil, errors.New(\"running libp2p with Swarm.Transports.Multiplexers.Yamux disabled is not supported\")\n\t}\n\n\treturn libp2p.Muxer(yamux.ID, yamux.DefaultTransport), nil\n}\n\nfunc SmuxTransport(tptConfig config.Transports) func() (opts Libp2pOpts, err error) {\n\treturn func() (opts Libp2pOpts, err error) {\n\t\tres, err := makeSmuxTransportOption(tptConfig)\n\t\tif err != nil {\n\t\t\treturn opts, err\n\t\t}\n\t\topts.Opts = append(opts.Opts, res)\n\t\treturn opts, nil\n\t}\n}","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/node/libp2p/smux.go#L1-L33","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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`"],"exampleFix":"# before (systemd unit / docker entrypoint)\nEnvironment=LIBP2P_MUX_PREFS=mplex\nipfs daemon\n\n# after\n# remove the env line, then:\nipfs config --json Swarm.Transports.Multiplexers '{\"Yamux\": 1}'\nipfs daemon","handlingStrategy":"validation","validationCode":"// before starting the daemon\nif [ -n \"$LIBP2P_MUX_PREFS\" ]; then\n  echo \"error: LIBP2P_MUX_PREFS is no longer supported; use Swarm.Transports.Multiplexers\" >&2\n  exit 1\nfi\nipfs daemon","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["libp2p","config","muxer","deprecation"],"backgroundTag":"removed-environment-variable","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"}