What causes "%s: MFS destination directory %q does not exist: %w" in ipfs/kubo?

Create the directory first: `ipfs files mkdir -p /data`

%s: MFS destination directory %q does not exist: %w

Error message

%s: MFS destination directory %q does not exist: %w

What it means

When the `--to-files` destination ends with '/', it is treated as a directory and kubo looks it up under the MFS root to confirm it exists. If mfs.Lookup fails (path absent), the error is wrapped with the option name and destination for context.

Source

Thrown at core/commands/add.go:595

						errCh <- fmt.Errorf("%s: cannot add unnamed files to MFS", toFilesOptionName)
						return
					}

					if toFilesStr == "" {
						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))

View on GitHub (pinned to 329838acdf)

Solutions

Create the directory first: `ipfs files mkdir -p /data`
Drop the trailing slash so the destination is treated as a file path
Verify the target exists with `ipfs files stat /data/` before adding

Example fix

// before
ipfs add --to-files=/data/ report.md   # /data does not exist
// after
ipfs files mkdir -p /data && ipfs add --to-files=/data/ report.md

Defensive patterns

Strategy: try-catch

Validate before calling

if strings.HasSuffix(dst, "/") {
  if _, err := api.Files().Stat(ctx, dst); err != nil {
    return fmt.Errorf("MFS directory missing: %w", err)
  }
}

Try / catch

err := ipfsAdd(ctx, args...)
var cmdErr *cmds.Error
if errors.As(err, &cmdErr) && strings.Contains(cmdErr.Message, "does not exist") {
  if err := api.Files().Mkdir(ctx, dirDst, optFiles.MkdirParents(true)); err == nil {
    err = ipfsAdd(ctx, args...)
  }
}

Prevention

Run `ipfs files mkdir -p` for destination directories before bulk adds
Stat the MFS destination before invoking add in scripts
Avoid trailing-slash directory destinations unless the dir is known to exist

When it happens

Trigger: `ipfs add --to-files=/nonexistent/ file` (trailing slash, directory missing in MFS); typo'd MFS directories; destination removed by a prior `ipfs files rm -r` before the add ran.

Common situations: Scripts assuming a target directory exists in MFS; fresh nodes with empty /; destinations under paths never created via `ipfs files mkdir -p`.

Related errors

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