What causes "%s: cannot add unnamed files to MFS" in ipfs/kubo?

Add a real file path so the entry has a name, instead of stdin

%s: cannot add unnamed files to MFS

Error message

%s: cannot add unnamed files to MFS

What it means

With `--to-files`, kubo links each added entry into MFS using the entry's name. Stdin adds (`ipfs add -`) have no name, so there is nothing to link the node under; the add goroutine reports this error through errCh.

Source

Thrown at core/commands/add.go:577

				pathAdded, err := api.Unixfs().Add(req.Context, addit.Node(), opts...)
				if err != nil {
					errCh <- err
					return
				}

				// Store the root CID for potential fast-provide operation
				lastRootCid = pathAdded

				// creating MFS pointers when optional --to-files is set
				if toFilesSet {
					// The link creates new MFS directory nodes that are not
					// pinned, so guard it against a concurrent GC. For an
					// unpinned add the lock is already held above.
					if dopin {
						defer ipfsNode.Blockstore.PinLock(req.Context).Unlock(req.Context)
					}
					if addit.Name() == "" {
						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)

View on GitHub (pinned to 329838acdf)

Solutions

Add a real file path so the entry has a name, instead of stdin
Write stdin to a temp file first, then `ipfs add --to-files=/data tmpfile`
Use a plain add for stdin, then `ipfs files cp /ipfs/<cid> /data/name`

Example fix

// before
cat stream.bin | ipfs add --to-files=/data -
// after
ipfs add --to-files=/data /tmp/stream.bin

Defensive patterns

Strategy: validation

Validate before calling

if toFilesSet && (inputIsStdin || entryName == "") {
  return errors.New("--to-files requires named inputs; stdin is not supported")
}

Prevention

Never combine stdin input with --to-files
Spool stdin to a temp file to give it a name before adding

When it happens

Trigger: `ipfs add --to-files=/data -` (reading from stdin); any files.File entry whose Name() is empty combined with ToFiles set.

Common situations: Piping downloads or generated bytes into `ipfs add --to-files=...`; CI scripts streaming tarballs via stdin into MFS.

Related errors

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