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

Create parent directories first: `ipfs files mkdir -p `

cp: cannot put node in path %s: %s

Error message

cp: cannot put node in path %s: %s

What it means

After resolving and validating the source, `ipfs files cp` calls mfs.PutNode to place the node at dst; this error wraps that failure. Typical causes are missing parent directories in dst, dst already existing (without --force), or invalid dst path syntax.

Source

Thrown at core/commands/files.go:597

			}
		}

		force, _ := req.Options[forceOptionName].(bool)
		if force {
			if err = unlinkNodeIfExists(nd, dst); err != nil {
				return fmt.Errorf("cp: cannot unlink existing file: %s", err)
			}
		}

		flush, _ := req.Options[filesFlushOptionName].(bool)

		if err := updateNoFlushCounter(nd, flush); err != nil {
			return err
		}

		err = mfs.PutNode(nd.FilesRoot, dst, node)
		if err != nil {
			return fmt.Errorf("cp: cannot put node in path %s: %s", dst, err)
		}
		if flush {
			if _, err := mfs.FlushPath(req.Context, nd.FilesRoot, dst); err != nil {
				return fmt.Errorf("cp: cannot flush the created file %s: %s", dst, err)
			}
			// Flush parent to clear directory cache and free memory.
			parent := gopath.Dir(dst)
			if _, err = mfs.FlushPath(req.Context, nd.FilesRoot, parent); err != nil {
				return fmt.Errorf("cp: cannot flush the created file's parent folder %s: %s", dst, err)
			}
		}

		return nil
	},
}

func getNodeFromPath(ctx context.Context, node *core.IpfsNode, api iface.CoreAPI, p string) (ipld.Node, error) {
	// A content path or native IPFS URI (/ipfs/cid, ipfs://cid, /ipns/name, ...)

View on GitHub (pinned to 329838acdf)

Solutions

Create parent directories first: `ipfs files mkdir -p <parent-of-dst>`
If dst exists, remove it (`ipfs files rm -r <dst>`) or re-run with `--force`
Validate dst syntax: use `files rm` naming conventions, and avoid trailing slashes unless intending base-name derivation
Check `ipfs files stat /` to confirm MFS root is healthy

Example fix

// before
ipfs files cp /ipfs/Qm... /nonexistent/dir/file
// error: cp: cannot put node in path /nonexistent/dir/file: ...

// after
ipfs files mkdir -p /nonexistent/dir
ipfs files cp /ipfs/Qm... /nonexistent/dir/file

Defensive patterns

Strategy: validation

Validate before calling

// create parents and clear collisions before cp
run("ipfs", "files", "mkdir", "-p", filepath.Dir(dst))
if _, err := run("ipfs", "files", "stat", dst); err == nil {
    run("ipfs", "files", "rm", "-r", dst) // or use --force
}

Try / catch

if err := ipfsFilesCp(src, dst); err != nil {
    if strings.Contains(err.Error(), "cannot put node in path") {
        // mkdir -p parents, remove existing dst, retry
    }
}

Prevention

Always `ipfs files mkdir -p` the destination parent first
Decide explicitly between --force and pre-removal of dst
Avoid trailing slashes in dst unless base-name derivation is intended

When it happens

Trigger: Running `ipfs files cp <src> <dst>` where dst's parent doesn't exist in MFS, dst already exists and no --force was given, dst is malformed, or the MFS write fails (e.g. root not writable, path resolves through a non-directory).

Common situations: Forgetting to `ipfs files mkdir -p` the destination folder; copying without --force over an existing entry; using a trailing-slash dst where base-name derivation fails.

Related errors

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