ipfs/kubo · critical

serveHTTPGateway: GetConfig() failed: %s

Error message

serveHTTPGateway: GetConfig() failed: %s

What it means

serveHTTPGateway wraps any failure from cctx.GetConfig() (which loads the node's $IPFS_PATH/config file) with this message during gateway startup. The gateway cannot determine Addresses.Gateway or Gateway options without the config, so daemon startup aborts. The wrapped inner error contains the actual reason (unreadable file, invalid JSON, repo not initialized).

Source

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

	// Print listeners
	for _, host := range hosts {
		protocolsSet := addrMap[host]
		protocols := make([]string, 0, len(protocolsSet))
		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)
		}

View on GitHub (pinned to 329838acdf)

Solutions

1. Run `ipfs init` if the repo does not exist (check IPFS_PATH).
2. Validate the config: `ipfs config show` or `jq . $IPFS_PATH/config` to find JSON syntax errors and fix them.
3. Fix file permissions on $IPFS_PATH/config so the daemon user can read it.
4. Verify IPFS_PATH points to the intended repo, not an empty or wrong directory.

Example fix

// before: daemon fails
$ IPFS_PATH=/nonexistent ipfs daemon
serveHTTPGateway: GetConfig() failed: ... no such file or directory
// after
$ ipfs init
$ ipfs daemon

if [ ! -f "$IPFS_PATH/config" ]; then ipfs init; fi
jq empty "$IPFS_PATH/config" || { echo 'config JSON invalid'; exit 1; }

err := daemon.Serve(ctx)
if err != nil && strings.Contains(err.Error(), "GetConfig() failed") {
    log.Fatalf("fix $IPFS_PATH/config and re-init: %v", err)
}

When it happens

Trigger: ipfs daemon startup when cctx.GetConfig() returns an error: config file missing, unreadable permissions, malformed JSON, or repo not initialized.

Common situations: Running the daemon before `ipfs init`; corrupted or hand-edited config JSON; wrong IPFS_PATH pointing to a non-repo directory; permission changes after running as a different user (root vs. user).

Related errors

• could not read config: %w
• serveHTTPGateway: socket activation failed: %s
• serveHTTPGateway: invalid gateway address: %q (err: %s)
• serveHTTPGateway: %w
• serveHTTPGateway: manet.ToNetAddr() failed: %w

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