ipfs/kubo · error

serveHTTPGateway: socket activation failed: %s

Error message

serveHTTPGateway: socket activation failed: %s

What it means

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.

Source

Thrown at cmd/ipfs/kubo/daemon.go:1071

		for protocol := range protocolsSet {
			protocols = append(protocols, protocol)
		}
		sort.Strings(protocols)
		fmt.Printf("Swarm listening on %s (%s)\n", host, strings.Join(protocols, "+"))
	}
	fmt.Printf("Run 'ipfs id' to inspect announced and discovered multiaddrs of this node.\n")
}

// serveHTTPGateway collects options, creates listener, prints status message and starts serving requests.
func serveHTTPGateway(req *cmds.Request, cctx *oldcmds.Context) (<-chan error, error) {
	cfg, err := cctx.GetConfig()
	if err != nil {
		return nil, fmt.Errorf("serveHTTPGateway: GetConfig() failed: %s", err)
	}

	listeners, err := sockets.TakeListeners("io.ipfs.gateway")
	if err != nil {
		return nil, fmt.Errorf("serveHTTPGateway: socket activation failed: %s", err)
	}

	listenerAddrs := make(map[string]bool, len(listeners))
	for _, listener := range listeners {
		listenerAddrs[string(listener.Multiaddr().Bytes())] = true
	}

	gatewayAddrs := cfg.Addresses.Gateway
	for _, addr := range gatewayAddrs {
		gatewayMaddr, err := ma.NewMultiaddr(addr)
		if err != nil {
			return nil, fmt.Errorf("serveHTTPGateway: invalid gateway address: %q (err: %s)", addr, err)
		}

		if listenerAddrs[string(gatewayMaddr.Bytes())] {
			continue
		}

View on GitHub (pinned to 329838acdf)

Solutions

1. Verify the systemd socket unit passes the FD and matches the file-descriptor name io.ipfs.gateway.
2. Check LISTEN_FDS/LISTEN_PID env vars are set correctly by the supervisor.
3. Ensure no stale daemon process still holds the inherited FDs (pkill -f "ipfs daemon").
4. If you do not need socket activation, unset LISTEN_* env vars and let kubo bind Addresses.Gateway itself.

Example fix

# before (systemd unit missing socket)
[Service]
Environment=LISTEN_FDS=1
// after: pair with a socket unit
# ipfs-gateway.socket
[Socket]
ListenStream=0.0.0.0:8080
FileDescriptorName=io.ipfs.gateway

if [ -n "$LISTEN_FDS" ]; then
  echo "socket activation active; ensure unit names FD io.ipfs.gateway"
else
  echo "plain start; kubo will bind Addresses.Gateway itself"
fi

err := serveHTTPGateway(req, cctx)
if err != nil && strings.Contains(err.Error(), "socket activation failed") {
    log.Fatalf("check systemd socket unit / LISTEN_FDS: %v", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• serveHTTPApi: socket activation failed: %s
• serveHTTPGateway: GetConfig() failed: %s
• ipfs api address could not be found
• cannot get migrations from unknown fetcher type
• nothing downloaded by ipfs fetcher

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