{"record":{"id":"1f7f31e0b9730c9b","repo":"ipfs/kubo","slug":"s-cannot-put-node-in-path-q-w","errorCode":null,"errorMessage":"%s: cannot put node in path %q: %w","messagePattern":"(.+?): cannot put node in path %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/add.go","lineNumber":627,"sourceCode":"\t\t\t\t\t\terrCh <- fmt.Errorf(\"%s: MFS destination is a file: only one entry can be copied to %q\", toFilesOptionName, toFilesDst)\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\n\t\t\t\t\t_, err = mfs.Lookup(ipfsNode.FilesRoot, gopath.Dir(toFilesDst))\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\terrCh <- fmt.Errorf(\"%s: MFS destination parent %q %q does not exist: %w\", toFilesOptionName, toFilesDst, gopath.Dir(toFilesDst), err)\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\n\t\t\t\t\tvar nodeAdded ipld.Node\n\t\t\t\t\tnodeAdded, err = api.Dag().Get(req.Context, pathAdded.RootCid())\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\terrCh <- err\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\t\t\t\t\terr = mfs.PutNode(ipfsNode.FilesRoot, toFilesDst, nodeAdded)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\terrCh <- fmt.Errorf(\"%s: cannot put node in path %q: %w\", toFilesOptionName, toFilesDst, err)\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\t\t\t\t\tfileAddedToMFS = true\n\t\t\t\t}\n\t\t\t\terrCh <- err\n\t\t\t}()\n\n\t\t\tfor event := range events {\n\t\t\t\toutput, ok := event.(*coreiface.AddEvent)\n\t\t\t\tif !ok {\n\t\t\t\t\treturn errors.New(\"unknown event type\")\n\t\t\t\t}\n\n\t\t\t\th := \"\"\n\t\t\t\tif (output.Path != path.ImmutablePath{}) {\n\t\t\t\t\th = enc.Encode(output.Path.RootCid())\n\t\t\t\t}\n","sourceCodeStart":609,"sourceCodeEnd":645,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/add.go#L609-L645","documentation":"mfs.PutNode failed while linking the freshly added DAG node at the --to-files destination. The lookup of the parent succeeded but the write itself failed; the wrapped error carries the underlying cause (e.g. destination is an existing file, permission/lock issue, or MFS internal error).","triggerScenarios":"Run `ipfs add --to-files /existing-file newfile` where the destination path already exists as a non-directory node and PutNode refuses to replace it; or MFS write fails mid-operation due to internal state errors.","commonSituations":"Destination path exists as a file (PutNode into a path whose basename slot is occupied by a file in some flows); concurrent `ipfs files` operations mutating MFS during add; read-only or corrupt repo state.","solutions":["Choose a destination path that does not already exist, or remove it first: ipfs files rm /path","Use a directory destination (trailing slash) so the file is placed under its own name","Inspect the wrapped cause (%w) in the message for the underlying MFS failure and address it"],"exampleFix":"// before\nipfs add --to-files /notes.txt newfile.txt   # /notes.txt exists\n// after\nipfs add --to-files /notes/ newfile.txt","handlingStrategy":"try-catch","validationCode":"// check the destination slot is free before adding\nif ipfs files stat \"$DST\" >/dev/null 2>&1; then\n  ipfs files rm -r \"$DST\"\nfi\nipfs add --to-files \"$DST\" \"$FILE\"","typeGuard":null,"tryCatchPattern":"if err := cmd.Run(); err != nil {\n  var putErr *fs.PathError // inspect wrapped cause from 'cannot put node in path'\n  log.Printf(\"MFS put failed: %v\", err)\n  // recover: retry with a fresh destination path\n}","preventionTips":["Pick destination paths that do not already exist in MFS","Avoid concurrent `ipfs files` writes while an --to-files add is running","Always log the wrapped error (%w) to see the true MFS cause"],"tags":["cli","mfs","to-files","putnode"],"backgroundTag":"mfs-put-node-failed","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"}