{"record":{"id":"818dad358e778e2d","repo":"ipfs/kubo","slug":"servehttpgateway-socket-activation-failed-s","errorCode":null,"errorMessage":"serveHTTPGateway: socket activation failed: %s","messagePattern":"serveHTTPGateway: socket activation failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/kubo/daemon.go","lineNumber":1071,"sourceCode":"\t\tfor protocol := range protocolsSet {\n\t\t\tprotocols = append(protocols, protocol)\n\t\t}\n\t\tsort.Strings(protocols)\n\t\tfmt.Printf(\"Swarm listening on %s (%s)\\n\", host, strings.Join(protocols, \"+\"))\n\t}\n\tfmt.Printf(\"Run 'ipfs id' to inspect announced and discovered multiaddrs of this node.\\n\")\n}\n\n// serveHTTPGateway collects options, creates listener, prints status message and starts serving requests.\nfunc serveHTTPGateway(req *cmds.Request, cctx *oldcmds.Context) (<-chan error, error) {\n\tcfg, err := cctx.GetConfig()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"serveHTTPGateway: GetConfig() failed: %s\", err)\n\t}\n\n\tlisteners, err := sockets.TakeListeners(\"io.ipfs.gateway\")\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"serveHTTPGateway: socket activation failed: %s\", err)\n\t}\n\n\tlistenerAddrs := make(map[string]bool, len(listeners))\n\tfor _, listener := range listeners {\n\t\tlistenerAddrs[string(listener.Multiaddr().Bytes())] = true\n\t}\n\n\tgatewayAddrs := cfg.Addresses.Gateway\n\tfor _, addr := range gatewayAddrs {\n\t\tgatewayMaddr, err := ma.NewMultiaddr(addr)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"serveHTTPGateway: invalid gateway address: %q (err: %s)\", addr, err)\n\t\t}\n\n\t\tif listenerAddrs[string(gatewayMaddr.Bytes())] {\n\t\t\tcontinue\n\t\t}\n","sourceCodeStart":1053,"sourceCodeEnd":1089,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/daemon.go#L1053-L1089","documentation":"When systemd-style socket activation is enabled, serveHTTPGateway asks the sockets package for pre-inherited listeners under the service name \"io.ipfs.gateway\". If socket activation is configured but the FDs cannot be taken (bad env, wrong service name, FDs already consumed), this error is thrown and the gateway does not start.","triggerScenarios":"Starting the daemon under systemd socket activation (LISTEN_FDS set) when TakeListeners(\"io.ipfs.gateway\") fails: mismatched unit file, missing io.ipfs.gateway prefix, FDs not passed, or a previous daemon still holding them.","commonSituations":"Systemd unit misconfigured (wrong ListenStream/Service names), running under a supervisor that sets LISTEN_* vars but does not pass sockets, mixed socket-activation and manual runs.","solutions":["Verify the systemd socket unit passes the FD and matches the file-descriptor name io.ipfs.gateway.","Check LISTEN_FDS/LISTEN_PID env vars are set correctly by the supervisor.","Ensure no stale daemon process still holds the inherited FDs (pkill -f \"ipfs daemon\").","If you do not need socket activation, unset LISTEN_* env vars and let kubo bind Addresses.Gateway itself."],"exampleFix":"# before (systemd unit missing socket)\n[Service]\nEnvironment=LISTEN_FDS=1\n// after: pair with a socket unit\n# ipfs-gateway.socket\n[Socket]\nListenStream=0.0.0.0:8080\nFileDescriptorName=io.ipfs.gateway","handlingStrategy":"validation","validationCode":"if [ -n \"$LISTEN_FDS\" ]; then\n  echo \"socket activation active; ensure unit names FD io.ipfs.gateway\"\nelse\n  echo \"plain start; kubo will bind Addresses.Gateway itself\"\nfi","typeGuard":null,"tryCatchPattern":"err := serveHTTPGateway(req, cctx)\nif err != nil && strings.Contains(err.Error(), \"socket activation failed\") {\n    log.Fatalf(\"check systemd socket unit / LISTEN_FDS: %v\", err)\n}","preventionTips":["Match the systemd socket unit's FileDescriptorName to io.ipfs.gateway.","Do not set LISTEN_* env vars unless a supervisor actually passes FDs.","Ensure only one process consumes the inherited FDs.","Test the unit with systemd-socket-activate before production."],"tags":["socket-activation","systemd","gateway","daemon"],"backgroundTag":"socket-activation-failed","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"}