ipfs/kubo · error

cannot manually publish while IPNS is mounted

Error message

cannot manually publish while IPNS is mounted

What it means

When the IPNS name is mounted over FUSE, manual IPNS publishes through the API are refused to avoid the mount and direct publishes diverging. checkPublishAllowed returns this error when a publish is attempted while n.Mounts.Ipns is active, unless the publish originates from FUSE itself (fusemount.IsPublish). It protects consistency between the mounted view and the record.

Source

Thrown at core/coreapi/coreapi.go:209

		pubSub: n.PubSub,

		nd:         n,
		parentOpts: settings,
	}

	subAPI.checkOnline = func(allowOffline bool) error {
		if !n.IsOnline && !allowOffline {
			return coreiface.ErrOffline
		}
		return nil
	}

	subAPI.checkPublishAllowed = func(ctx context.Context) error {
		if fusemount.IsPublish(ctx) {
			return nil
		}
		if n.Mounts.Ipns != nil && n.Mounts.Ipns.IsActive() {
			return errors.New("cannot manually publish while IPNS is mounted")
		}
		return nil
	}

	cfg, err := n.Repo.Config()
	if err != nil {
		return nil, err
	}

	if settings.Offline {
		cs := cfg.Ipns.ResolveCacheSize
		if cs == 0 {
			cs = node.DefaultIpnsCacheSize
		}
		if cs < 0 {
			return nil, errors.New("cannot specify negative resolve cache size")
		}

View on GitHub (pinned to 329838acdf)

Solutions

1. Unmount IPNS first ('ipfs mount' management / fusermount -u the ipns path), then publish
2. Publish through the mounted filesystem instead of the API (write to the mount) so the mount stays authoritative
3. Restart the node without the mount if publishing must be API-driven
4. Check 'ipfs mount' output to confirm the Ipns mount state before scripting publishes

Example fix

// before
ipfs name publish <cid>            # fails while mounted
// after
fusermount -u /ipns && ipfs name publish <cid>

cfg, _ := node.Repo.Config()
mountsActive := node.Mounts != nil && node.Mounts.Ipns != nil && node.Mounts.Ipns.IsActive()
if mountsActive {
    return errors.New("unmount IPNS (or publish via the mount) before name publish")
}

err := api.Name().Publish(ctx, pth, opts...)
if err != nil && strings.Contains(err.Error(), "cannot manually publish while IPNS is mounted") {
    return fmt.Errorf("unmount IPNS first or write through the /ipns mount: %w", err)
}
return err

When it happens

Trigger: Calling 'ipfs name publish ...' (RPC name/publish) on a node with 'ipfs mount' active for IPNS; publishing via the HTTP API while the local IPNS mount is up; scripts that mount IPNS and then publish records programmatically.

Common situations: Users who keep 'ipfs mount' running in the background and forget it before scripting name publishes; long-running desktop setups with FUSE mounts; CI jobs that mount IPNS then attempt publishes in the same session.

Related errors

• mountFuse: GetConfig() failed: %s
• mountFuse: ConstructNode() failed: %s
• %s path cannot be empty
• %s path (%q) does not exist: %w
• mounting %s: %w

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