cp: source must be a valid UnixFS (dag-pb or raw codec)

Error message

cp: source must be a valid UnixFS (dag-pb or raw codec)

What it means

`ipfs files cp` only accepts sources whose root block is valid UnixFS: either a dag-pb node containing UnixFS data or a raw block. The declared sentinel errFilesCpInvalidUnixFS is returned when the source node's codec is raw but the node is not a *dag.RawNode, or its codec is dag-pb but the node is not a *dag.ProtoNode, or the codec is neither raw nor dag-pb (see also index 273 for the dag-pb data parse failure variant).

Source

Thrown at core/commands/files.go:466

		if err != nil {
			return local, sizeLocal, err
		}

		childLocal, childLocalSize, err := walkBlock(ctx, dagserv, child)
		if err != nil {
			return local, sizeLocal, err
		}

		// Recursively add the child size
		local = local && childLocal
		sizeLocal += childLocalSize
	}

	return local, sizeLocal, nil
}

var errFilesCpInvalidUnixFS = errors.New("cp: source must be a valid UnixFS (dag-pb or raw codec)")
var filesCpCmd = &cmds.Command{
	Helptext: cmds.HelpText{
		Tagline: "Add references to IPFS files and directories in MFS (or copy within MFS).",
		ShortDescription: `
"ipfs files cp" can be used to add references to any IPFS file or directory
(usually in the form /ipfs/<CID>, but also any resolvable path) into MFS.
This performs a lazy copy: the full DAG will not be fetched, only the root
node being copied.

It can also be used to copy files within MFS, but in the case when an
IPFS-path matches an existing MFS path, the IPFS path wins.

In order to add content to MFS from disk, you can use "ipfs add" to obtain the
IPFS Content Identifier and then "ipfs files cp" to copy it into MFS:

$ ipfs add --quieter --pin=false <your file>
# ...
# ... outputs the root CID at the end

View on GitHub (pinned to 329838acdf)

Solutions

Check the source CID codec with `ipfs cid info <cid>`; only raw and dag-pb sources are supported
Wrap non-UnixFS content in a UnixFS node first, e.g. `ipfs dag put` is not enough — use `ipfs add` or an `ipfs files cp` of a UnixFS root
If the data is a dag-cbor/dag-json document, it cannot be placed in MFS directly; export it and re-add as a file
Fetch the content with `ipfs get` and `ipfs add` it, then copy the new CID into MFS

Example fix

// before: copying a dag-cbor root directly
ipfs files cp /ipfs/bafyrei...cbor /my-file
// error: cp: source must be a valid UnixFS (dag-pb or raw codec)

// after: re-add the content as UnixFS, then copy
ipfs get /ipfs/bafyrei...cbor -o tmpfile
ipfs add -q tmpfile
ipfs files cp /ipfs/<new-unixfs-cid> /my-file

Defensive patterns

Strategy: validation

Validate before calling

codec := ipfsCidInfoCodec(cid) // e.g. via `ipfs cid info`
if codec != "raw" && codec != "dag-pb" {
    return fmt.Errorf("cid %s codec %s unsupported for files cp", cid, codec)
}

Type guard

func isUnixFSRoot(cid string) bool {
    out, err := run("ipfs", "cid", "info", cid)
    if err != nil { return false }
    return strings.Contains(out, "raw") || strings.Contains(out, "dag-pb")
}

Try / catch

if err := ipfsFilesCp(src, dst); err != nil {
    if strings.Contains(err.Error(), "source must be a valid UnixFS") {
        // re-add via `ipfs add` to obtain a UnixFS root, then retry
    }
}

Prevention

Check CID codec with `ipfs cid info` before cp into MFS
Only cp CIDs produced by `ipfs add` or known raw leaves
Remember dag-cbor/dag-json documents are not placeable in MFS

When it happens

Trigger: Running `ipfs files cp /ipfs/<cid> /dst` where <cid> has a codec other than raw or dag-pb (e.g. dag-cbor, dag-json), or where the in-memory node type does not match the CID codec.

Common situations: Copying a dag-cbor or dag-json document into MFS; attempting to cp a CID whose multicodec is unixfs-incompatible; copying blocks fetched as raw leaves but represented by a different node type.

Related errors

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