ipfs/kubo · error

serveHTTPApi: SetAPIAddr() failed: %w

Error message

serveHTTPApi: SetAPIAddr() failed: %w

What it means

After API listeners are ready, serveHTTPApi writes the API multiaddr (with 0.0.0.0/:: rewritten to 127.0.0.1) into the repo via node.Repo.SetAPIAddr so clients can discover it. If persisting that address fails, the daemon aborts with this error. It signals a repo/datastore-level failure, not a network one.

Source

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

			readyChannels[i] = make(chan struct{})
			ready := readyChannels[i]
			wg.Go(func() {
				errc <- corehttp.ServeWithReady(node, manet.NetListener(lis), ready, opts...)
			})
		}

		// Wait for all listeners to be ready or any to fail
		for _, ready := range readyChannels {
			select {
			case <-ready:
				// This listener is ready
			case err := <-errc:
				return nil, fmt.Errorf("serveHTTPApi: %w", err)
			}
		}

		if err := node.Repo.SetAPIAddr(rewriteMaddrToUseLocalhostIfItsAny(listeners[0].Multiaddr())); err != nil {
			return nil, fmt.Errorf("serveHTTPApi: SetAPIAddr() failed: %w", err)
		}
	}

	go func() {
		wg.Wait()
		close(errc)
	}()

	return errc, nil
}

func rewriteMaddrToUseLocalhostIfItsAny(maddr ma.Multiaddr) ma.Multiaddr {
	first, rest := ma.SplitFirst(maddr)

	switch {
	case first.Equal(&manet.IP4Unspecified[0]):
		return manet.IP4Loopback.Encapsulate(rest)
	case first.Equal(&manet.IP6Unspecified[0]):

View on GitHub (pinned to 329838acdf)

Solutions

1. Check filesystem writability of IPFS_PATH: `touch $IPFS_PATH/testfile` and fix mount/permissions (`chown` to the daemon user)
2. Free disk space or raise container disk quota if the volume is full
3. Ensure the same user runs init and daemon; do not run as root against a user's repo
4. If the `api` file is corrupted, stop the daemon and delete `$IPFS_PATH/api` (it is regenerated)

Example fix

// before
$ ls -ld ~/.ipfs
drwxr-xr-x 1 root root ~/.ipfs   # wrong owner
Error: serveHTTPApi: SetAPIAddr() failed: ... permission denied

// after
$ sudo chown -R ipfs:ipfs /data/ipfs
$ IPFS_PATH=/data/ipfs ipfs daemon

// verify repo path is writable by the daemon user before start
IPFS_PATH=/data/ipfs; test -w "$IPFS_PATH" && test -w "$IPFS_PATH/datastore" || echo "IPFS_PATH not writable"; df -h "$IPFS_PATH" | awk 'NR==2{if($5+0>95) print "disk nearly full"}'

if err := daemonFunc(...); err != nil {
    if strings.Contains(err.Error(), "SetAPIAddr() failed") {
        log.Fatalf("repo write failure: %v", err) // check fs perms/space
    }
}

When it happens

Trigger: `ipfs daemon` starts listeners fine, but SetAPIAddr fails when writing the `api` file in the repo fails: read-only filesystem, full disk, permission denied on IPFS_PATH, or repo lock/datastore errors.

Common situations: IPFS_PATH on a mounted read-only volume or a crashed disk; running the daemon as a different user than `ipfs init` (permission denied); disk quota exceeded in containers.

Related errors

• %s path (%q) does not exist: %w
• %s is not writeable by the current user
• cannot write to %s, incorrect permissions
• opening repo (is the daemon running?): %w
• creating temporary file for %s: %w

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