What causes "%s: MFS destination %q is not a directory" in ipfs/kubo?

Remove the trailing slash from --to-files to target a file destination directly, e.g. --to-files /path/file.txt

%s: MFS destination %q is not a directory

Error message

%s: MFS destination %q is not a directory

What it means

`ipfs add --to-files <dst>` requires the MFS destination to be a directory when the destination path ends with '/'. The add command looked up the target MFS node and found it is not a directory (mfs.TDir), so it cannot append the added file's name beneath it. This is a pre-flight destination-type check in the --to-files handling, thrown before any MFS write occurs.

Source

Thrown at core/commands/add.go:600

						toFilesStr = "/"
					}
					toFilesDst, err := checkPath(toFilesStr)
					if err != nil {
						errCh <- fmt.Errorf("%s: %w", toFilesOptionName, err)
						return
					}
					dstAsDir := toFilesDst[len(toFilesDst)-1] == '/'

					if dstAsDir {
						mfsNode, err := mfs.Lookup(ipfsNode.FilesRoot, toFilesDst)
						// confirm dst exists
						if err != nil {
							errCh <- fmt.Errorf("%s: MFS destination directory %q does not exist: %w", toFilesOptionName, toFilesDst, err)
							return
						}
						// confirm dst is a dir
						if mfsNode.Type() != mfs.TDir {
							errCh <- fmt.Errorf("%s: MFS destination %q is not a directory", toFilesOptionName, toFilesDst)
							return
						}
						// if MFS destination is a dir, append filename to the dir path
						toFilesDst += gopath.Base(addit.Name())
					}

					// error if we try to overwrite a preexisting file destination
					if fileAddedToMFS && !dstAsDir {
						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
					}

View on GitHub (pinned to 329838acdf)

Solutions

Remove the trailing slash from --to-files to target a file destination directly, e.g. --to-files /path/file.txt
Ensure the destination directory exists in MFS first: ipfs files mkdir -p /path/dir
Verify the destination type with `ipfs files stat /path` and pick the correct path

Example fix

// before
ipfs add --to-files /docs/ myfile.txt   # /docs is an existing MFS file
// after
ipfs files mkdir -p /docs
ipfs add --to-files /docs/ myfile.txt

Defensive patterns

Strategy: validation

Validate before calling

// shell pre-check before ipfs add --to-files /path/
type=$(ipfs files stat /path | head -1)
[ "$type" = "directory" ] || ipfs files mkdir -p /path

Prevention

Only use a trailing slash on --to-files when the destination is a known MFS directory
Create destination directories with `ipfs files mkdir -p` first
Check `ipfs files stat` on the destination before scripting the add

When it happens

Trigger: Run `ipfs add --to-files /somepath/` (trailing slash forces directory interpretation) where /somepath exists in MFS but is a regular file, not a directory; the lookup succeeds but mfsNode.Type() != mfs.TDir, producing '<dst>: MFS destination "/somepath/" is not a directory'.

Common situations: Users pass an existing MFS file path with a trailing slash believing it creates the file; scripts reuse a destination path that was previously created as a file; confusion between 'destination is the file itself' vs 'destination is the parent directory to place it in'.

Related errors

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