ipfs/kubo · error

serveHTTPGateway: SetGatewayAddr() failed: %w

Error message

serveHTTPGateway: SetGatewayAddr() failed: %w

What it means

To make `ipfs daemon` discoverable, kubo persists the resolved gateway address into the repo via node.Repo.SetGatewayAddr(addr). This error wraps a failure writing that address (repo/datastore write error), causing gateway startup to abort even though the listener is already bound.

Source

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

			})
		}

		// 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("serveHTTPGateway: %w", err)
			}
		}

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

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

	return errc, nil
}

const gatewayProtocolID protocol.ID = "/ipfs/gateway" // FIXME: specify https://github.com/ipfs/specs/issues/433

func serveTrustlessGatewayOverLibp2p(cctx *oldcmds.Context) (<-chan error, error) {
	node, err := cctx.ConstructNode()
	if err != nil {
		return nil, fmt.Errorf("serveHTTPGatewayOverLibp2p: ConstructNode() failed: %s", err)
	}

View on GitHub (pinned to 329838acdf)

Solutions

1. Ensure $IPFS_PATH is writable by the daemon user (check ownership and mount ro/rw).
2. Free disk space if the datastore reports ENOSPC in the wrapped error.
3. Avoid bind-mounting the repo read-only in containers; mount rw or point IPFS_PATH at a writable volume.
4. Re-run `ipfs repo fsck` if a prior crash left the repo in a bad state.

Example fix

// before: repo read-only in container
-v /snapshots/ipfs:/data/ipfs:ro
// after
-v ipfs-data:/data/ipfs:rw

f, err := os.OpenFile(filepath.Join(ipfsPath, "config"), os.O_WRONLY, 0)
if err != nil {
    return fmt.Errorf("repo not writable by daemon user: %w", err)
}
f.Close()

if err != nil && strings.Contains(err.Error(), "SetGatewayAddr() failed") {
    log.Fatalf("check $IPFS_PATH writability/disk space: %v", err)
}

When it happens

Trigger: node.Repo.SetGatewayAddr(addr) errors: repo closed or in read-only mode, datastore write failure, disk full, permission denied on the repo directory, or repo shutdown racing startup.

Common situations: Read-only mounts of $IPFS_PATH (containers, snapshots); disk full; repo owned by another user; FUSE/sync filesystems rejecting writes.

Related errors

• could not read config: %w
• failed to open repo: %w
• n.Err (server-provided bad-node error message)
• serveHTTPApi: ConstructNode() failed: %s
• serveHTTPApi: SetAPIAddr() failed: %w

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