{"record":{"id":"29aebac726f6a69a","repo":"ipfs/kubo","slug":"cannot-add-named-links-to-a-unixfs-s-node-only-d","errorCode":null,"errorMessage":"cannot add named links to a UnixFS %s node, only Directory nodes support link addition at the dag-pb level (see https://specs.ipfs.tech/unixfs/)","messagePattern":"cannot add named links to a UnixFS (.+?) node, only Directory nodes support link addition at the dag-pb level \\(see https://specs\\.ipfs\\.tech/unixfs/\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreapi/object.go","lineNumber":83,"sourceCode":"\t// https://specs.ipfs.tech/unixfs/#pbnode-links-name\n\t// https://github.com/ipfs/kubo/issues/7190\n\tif !options.SkipUnixFSValidation {\n\t\tfsNode, err := ft.FSNodeFromBytes(basePb.Data())\n\t\tif err != nil {\n\t\t\treturn path.ImmutablePath{}, fmt.Errorf(\n\t\t\t\t\"cannot add named links to a non-UnixFS dag-pb node; \" +\n\t\t\t\t\t\"pass --allow-non-unixfs to skip validation\")\n\t\t}\n\t\tswitch fsNode.Type() {\n\t\tcase ft.TDirectory:\n\t\t\t// plain directories: safe, no link-count metadata to desync\n\t\tcase ft.THAMTShard:\n\t\t\treturn path.ImmutablePath{}, fmt.Errorf(\n\t\t\t\t\"cannot add links to a HAMTShard at the dag-pb level \" +\n\t\t\t\t\t\"(would corrupt the HAMT bitfield); use 'ipfs files' \" +\n\t\t\t\t\t\"commands instead, or pass --allow-non-unixfs to override\")\n\t\tdefault:\n\t\t\treturn path.ImmutablePath{}, fmt.Errorf(\n\t\t\t\t\"cannot add named links to a UnixFS %s node, \"+\n\t\t\t\t\t\"only Directory nodes support link addition at the dag-pb level \"+\n\t\t\t\t\t\"(see https://specs.ipfs.tech/unixfs/)\",\n\t\t\t\tfsNode.Type())\n\t\t}\n\t}\n\n\tvar createfunc func() *dag.ProtoNode\n\tif options.Create {\n\t\tcreatefunc = ft.EmptyDirNode\n\t}\n\n\te := dagutils.NewDagEditor(basePb, api.dag)\n\n\terr = e.InsertNodeAtPath(ctx, name, childNd, createfunc)\n\tif err != nil {\n\t\treturn path.ImmutablePath{}, err\n\t}","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreapi/object.go#L65-L101","documentation":"AddLink at the dag-pb level only supports plain UnixFS Directory nodes. Other UnixFS node types (File, Raw, Symlink, Metadata...) have no meaningful 'named links' semantics for link addition and dagutils.Editor cannot keep their metadata consistent. The error reports the actual node type so the caller knows what they passed.","triggerScenarios":"AddLink on a resolved path whose root dag-pb node is a UnixFS node of any type other than TDirectory or THAMTShard (e.g. a file or raw leaf).","commonSituations":"Passing a file CID instead of a directory CID to object patch add-link; path resolution landing on an inner file node due to a typo'd path.","solutions":["Pass the directory CID/path, not a file or other node","Use 'ipfs files' / MFS API for modifying UnixFS content","Use --allow-non-unixfs to bypass validation if you explicitly want raw dag-pb editing"],"exampleFix":"// before\nipfs object patch add-link QmFileCid name.txt QmChild\n// after: resolve to the directory first\nipfs object patch add-link QmDirCid name.txt QmChild","handlingStrategy":"validation","validationCode":"fsNode, err := ft.FSNodeFromBytes(pbNode.Data())\nif err != nil || fsNode.Type() != ft.TDirectory {\n    // not a plain directory: refuse dag-pb link addition\n}","typeGuard":"func isPlainUnixFSDirectory(n ipld.Node) bool {\n\tpb, ok := n.(*dagpb.PBNode)\n\tif !ok { return false }\n\tfsn, err := ft.FSNodeFromBytes(pb.Data())\n\treturn err == nil && fsn.Type() == ft.TDirectory\n}","tryCatchPattern":null,"preventionTips":["Always pass directory paths, never file paths, to AddLink","Resolve paths with type checks before patch operations","Prefer MFS API for all UnixFS content edits"],"tags":["unixfs","dag-pb","node-type","deprecated-api"],"backgroundTag":"unixfs-non-directory-link-edit","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"}