{"record":{"id":"36a4ae830f3789c8","repo":"ipfs/kubo","slug":"cp-source-must-be-a-valid-unixfs-dag-pb-or-raw-c","errorCode":null,"errorMessage":"cp: source must be a valid UnixFS (dag-pb or raw codec)","messagePattern":"cp: source must be a valid UnixFS \\(dag-pb or raw codec\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/files.go","lineNumber":466,"sourceCode":"\n\t\tif err != nil {\n\t\t\treturn local, sizeLocal, err\n\t\t}\n\n\t\tchildLocal, childLocalSize, err := walkBlock(ctx, dagserv, child)\n\t\tif err != nil {\n\t\t\treturn local, sizeLocal, err\n\t\t}\n\n\t\t// Recursively add the child size\n\t\tlocal = local && childLocal\n\t\tsizeLocal += childLocalSize\n\t}\n\n\treturn local, sizeLocal, nil\n}\n\nvar errFilesCpInvalidUnixFS = errors.New(\"cp: source must be a valid UnixFS (dag-pb or raw codec)\")\nvar filesCpCmd = &cmds.Command{\n\tHelptext: cmds.HelpText{\n\t\tTagline: \"Add references to IPFS files and directories in MFS (or copy within MFS).\",\n\t\tShortDescription: `\n\"ipfs files cp\" can be used to add references to any IPFS file or directory\n(usually in the form /ipfs/<CID>, but also any resolvable path) into MFS.\nThis performs a lazy copy: the full DAG will not be fetched, only the root\nnode being copied.\n\nIt can also be used to copy files within MFS, but in the case when an\nIPFS-path matches an existing MFS path, the IPFS path wins.\n\nIn order to add content to MFS from disk, you can use \"ipfs add\" to obtain the\nIPFS Content Identifier and then \"ipfs files cp\" to copy it into MFS:\n\n$ ipfs add --quieter --pin=false <your file>\n# ...\n# ... outputs the root CID at the end","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/files.go#L448-L484","documentation":"`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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: copying a dag-cbor root directly\nipfs files cp /ipfs/bafyrei...cbor /my-file\n// error: cp: source must be a valid UnixFS (dag-pb or raw codec)\n\n// after: re-add the content as UnixFS, then copy\nipfs get /ipfs/bafyrei...cbor -o tmpfile\nipfs add -q tmpfile\nipfs files cp /ipfs/<new-unixfs-cid> /my-file","handlingStrategy":"validation","validationCode":"codec := ipfsCidInfoCodec(cid) // e.g. via `ipfs cid info`\nif codec != \"raw\" && codec != \"dag-pb\" {\n    return fmt.Errorf(\"cid %s codec %s unsupported for files cp\", cid, codec)\n}","typeGuard":"func isUnixFSRoot(cid string) bool {\n    out, err := run(\"ipfs\", \"cid\", \"info\", cid)\n    if err != nil { return false }\n    return strings.Contains(out, \"raw\") || strings.Contains(out, \"dag-pb\")\n}","tryCatchPattern":"if err := ipfsFilesCp(src, dst); err != nil {\n    if strings.Contains(err.Error(), \"source must be a valid UnixFS\") {\n        // re-add via `ipfs add` to obtain a UnixFS root, then retry\n    }\n}","preventionTips":["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"],"tags":["mfs","cli","unixfs","cid"],"backgroundTag":"invalid-unixfs-source","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}