What causes "%s: %w" in ipfs/kubo?

Use an absolute MFS path starting with '/', e.g. --to-files=/data/file.bin

%s: %w

Error message

%s: %w

What it means

Before linking into MFS, the `--to-files` value is normalized by checkPath, which rejects strings that are not valid MFS paths (e.g. missing the leading '/'). The underlying checkPath error is wrapped with the --to-files option name for context.

Source

Thrown at core/commands/add.go:586

				// 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)
							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())

View on GitHub (pinned to 329838acdf)

Solutions

Use an absolute MFS path starting with '/', e.g. --to-files=/data/file.bin
Validate/normalize the destination before invoking add (ensure a single leading slash)
Pass '/' explicitly when defaulting to the MFS root

Example fix

// before
ipfs add --to-files=docs/report.md report.md
// after
ipfs add --to-files=/docs/report.md report.md

Defensive patterns

Strategy: validation

Validate before calling

func normalizeMFSDst(p string) (string, error) {
  if !strings.HasPrefix(p, "/") {
    return "", fmt.Errorf("MFS path must be absolute: %q", p)
  }
  return path.Clean(p), nil
}

Prevention

Always build --to-files destinations with a leading '/'
Run paths through path.Clean and require absoluteness in shared helpers

When it happens

Trigger: `ipfs add --to-files=relative/path file` (no leading slash); a malformed or invalid destination string; programmatic RPC calls building ToFiles without normalizing the path.

Common situations: Scripts assembling destinations from variables and losing the leading slash; users confusing MFS paths with local filesystem paths.

Related errors

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