{"record":{"id":"1815187f07b97303","repo":"ipfs/kubo","slug":"cannot-manually-publish-while-ipns-is-mounted","errorCode":null,"errorMessage":"cannot manually publish while IPNS is mounted","messagePattern":"cannot manually publish while IPNS is mounted","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreapi/coreapi.go","lineNumber":209,"sourceCode":"\t\tpubSub: n.PubSub,\n\n\t\tnd:         n,\n\t\tparentOpts: settings,\n\t}\n\n\tsubAPI.checkOnline = func(allowOffline bool) error {\n\t\tif !n.IsOnline && !allowOffline {\n\t\t\treturn coreiface.ErrOffline\n\t\t}\n\t\treturn nil\n\t}\n\n\tsubAPI.checkPublishAllowed = func(ctx context.Context) error {\n\t\tif fusemount.IsPublish(ctx) {\n\t\t\treturn nil\n\t\t}\n\t\tif n.Mounts.Ipns != nil && n.Mounts.Ipns.IsActive() {\n\t\t\treturn errors.New(\"cannot manually publish while IPNS is mounted\")\n\t\t}\n\t\treturn nil\n\t}\n\n\tcfg, err := n.Repo.Config()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif settings.Offline {\n\t\tcs := cfg.Ipns.ResolveCacheSize\n\t\tif cs == 0 {\n\t\t\tcs = node.DefaultIpnsCacheSize\n\t\t}\n\t\tif cs < 0 {\n\t\t\treturn nil, errors.New(\"cannot specify negative resolve cache size\")\n\t\t}\n","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreapi/coreapi.go#L191-L227","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Unmount IPNS first ('ipfs mount' management / fusermount -u the ipns path), then publish","Publish through the mounted filesystem instead of the API (write to the mount) so the mount stays authoritative","Restart the node without the mount if publishing must be API-driven","Check 'ipfs mount' output to confirm the Ipns mount state before scripting publishes"],"exampleFix":"// before\nipfs name publish <cid>            # fails while mounted\n// after\nfusermount -u /ipns && ipfs name publish <cid>","handlingStrategy":"validation","validationCode":"cfg, _ := node.Repo.Config()\nmountsActive := node.Mounts != nil && node.Mounts.Ipns != nil && node.Mounts.Ipns.IsActive()\nif mountsActive {\n    return errors.New(\"unmount IPNS (or publish via the mount) before name publish\")\n}","typeGuard":null,"tryCatchPattern":"err := api.Name().Publish(ctx, pth, opts...)\nif err != nil && strings.Contains(err.Error(), \"cannot manually publish while IPNS is mounted\") {\n    return fmt.Errorf(\"unmount IPNS first or write through the /ipns mount: %w\", err)\n}\nreturn err","preventionTips":["Check 'ipfs mount' state before scripting name publishes","Prefer publishing via the FUSE mount when it is active","Avoid long-running IPNS mounts on nodes driven by API publishes"],"tags":["ipns","fuse","mount"],"backgroundTag":"publish-blocked-by-mount","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}