What causes "serveHTTPApi: socket activation failed: %s" in ipfs/kubo?

Start the daemon without socket activation (unset LISTEN_FDS/LISTEN_PID) to see if normal mode works

serveHTTPApi: socket activation failed: %s

Error message

serveHTTPApi: socket activation failed: %s

What it means

With systemd socket activation, serveHTTPApi tries to inherit pre-opened listeners under the name "io.ipfs.api" via sockets.TakeListeners; if the activation layer fails it aborts API setup with this wrapped error.

Source

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

		}
	}
	if len(errs) != 0 {
		return errors.Join(errs...)
	}

	return nil
}

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

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

	apiAddrs := make([]string, 0, 2)
	apiAddr, _ := req.Options[commands.ApiOption].(string)
	if apiAddr == "" {
		apiAddrs = cfg.Addresses.API
	} else {
		apiAddrs = append(apiAddrs, apiAddr)
	}

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

	for _, addr := range apiAddrs {
		apiMaddr, err := ma.NewMultiaddr(addr)
		if err != nil {

View on GitHub (pinned to 329838acdf)

Solutions

Start the daemon without socket activation (unset LISTEN_FDS/LISTEN_PID) to see if normal mode works
Fix the systemd .socket unit so its file descriptor name/count matches the io.ipfs.api expectation
Restart the service cleanly so systemd re-passes fresh listeners
Disable socket activation and let kubo bind Addresses.API itself

Defensive patterns

Strategy: fallback

Validate before calling

// detect socket-activation environment
if os.Getenv("LISTEN_FDS") != "" && !runningUnderSystemd() {
    // unset LISTEN_FDS/LISTEN_PID to avoid TakeListeners("io.ipfs.api") failures
}

Prevention

Only use socket activation with a properly configured systemd socket unit
Restart services cleanly so FDs are re-passed
Fall back to plain listen mode when activation env vars are stale

When it happens

Trigger: `ipfs daemon` launched under systemd/socket activation where FD_LISTEN environment/FDs are inconsistent, or sockets.ActivationListener cannot find/match the io.ipfs.api descriptors.

Common situations: Running the daemon under systemd with socket units misconfigured; stale FDs after service restart; launching with socket-activation env vars set outside systemd.

Related errors

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