What causes "%s: cannot put node in path %q: %w" in ipfs/kubo?

Choose a destination path that does not already exist, or remove it first: ipfs files rm /path

%s: cannot put node in path %q: %w

Error message

%s: cannot put node in path %q: %w

What it means

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).

Source

Thrown at core/commands/add.go:627

						errCh <- fmt.Errorf("%s: MFS destination is a file: only one entry can be copied to %q", toFilesOptionName, toFilesDst)
						return
					}

					_, err = mfs.Lookup(ipfsNode.FilesRoot, gopath.Dir(toFilesDst))
					if err != nil {
						errCh <- fmt.Errorf("%s: MFS destination parent %q %q does not exist: %w", toFilesOptionName, toFilesDst, gopath.Dir(toFilesDst), err)
						return
					}

					var nodeAdded ipld.Node
					nodeAdded, err = api.Dag().Get(req.Context, pathAdded.RootCid())
					if err != nil {
						errCh <- err
						return
					}
					err = mfs.PutNode(ipfsNode.FilesRoot, toFilesDst, nodeAdded)
					if err != nil {
						errCh <- fmt.Errorf("%s: cannot put node in path %q: %w", toFilesOptionName, toFilesDst, err)
						return
					}
					fileAddedToMFS = true
				}
				errCh <- err
			}()

			for event := range events {
				output, ok := event.(*coreiface.AddEvent)
				if !ok {
					return errors.New("unknown event type")
				}

				h := ""
				if (output.Path != path.ImmutablePath{}) {
					h = enc.Encode(output.Path.RootCid())
				}

View on GitHub (pinned to 329838acdf)

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

Example fix

// before
ipfs add --to-files /notes.txt newfile.txt   # /notes.txt exists
// after
ipfs add --to-files /notes/ newfile.txt

Defensive patterns

Strategy: try-catch

Validate before calling

// check the destination slot is free before adding
if ipfs files stat "$DST" >/dev/null 2>&1; then
  ipfs files rm -r "$DST"
fi
ipfs add --to-files "$DST" "$FILE"

Try / catch

if err := cmd.Run(); err != nil {
  var putErr *fs.PathError // inspect wrapped cause from 'cannot put node in path'
  log.Printf("MFS put failed: %v", err)
  // recover: retry with a fresh destination path
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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