{"record":{"id":"78478071533e605e","repo":"ipfs/kubo","slug":"new-root-s-does-not-exist-locally-fetch-it-first","errorCode":null,"errorMessage":"new root %s does not exist locally; fetch it first with 'ipfs block get'","messagePattern":"new root (.+?) does not exist locally; fetch it first with 'ipfs block get'","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/files.go","lineNumber":1776,"sourceCode":"\t\trepo, err := fsrepo.Open(cfgRoot)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"opening repo (is the daemon running?): %w\", err)\n\t\t}\n\t\tdefer repo.Close()\n\n\t\tlocalDS := repo.Datastore()\n\t\tbs := bstore.NewBlockstore(localDS)\n\n\t\t// Check new root exists locally and is a directory\n\t\thasBlock, err := bs.Has(req.Context, newRootCid)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"checking if new root exists: %w\", err)\n\t\t}\n\t\tif !hasBlock {\n\t\t\t// Special case: empty dir is always available (hardcoded in boxo)\n\t\t\temptyDirCid := ft.EmptyDirNode().Cid()\n\t\t\tif !newRootCid.Equals(emptyDirCid) {\n\t\t\t\treturn fmt.Errorf(\"new root %s does not exist locally; fetch it first with 'ipfs block get'\", enc.Encode(newRootCid))\n\t\t\t}\n\t\t}\n\n\t\t// Validate it's a directory (not a file)\n\t\tif hasBlock {\n\t\t\tblk, err := bs.Get(req.Context, newRootCid)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"reading new root block: %w\", err)\n\t\t\t}\n\t\t\tpbNode, err := dag.DecodeProtobuf(blk.RawData())\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"new root is not a valid dag-pb node: %w\", err)\n\t\t\t}\n\t\t\tfsNode, err := ft.FSNodeFromBytes(pbNode.Data())\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"new root is not a valid UnixFS node: %w\", err)\n\t\t\t}\n\t\t\tif fsNode.Type() != ft.TDirectory && fsNode.Type() != ft.THAMTShard {","sourceCodeStart":1758,"sourceCodeEnd":1794,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/files.go#L1758-L1794","documentation":"`ipfs files chroot` requires the new root to be present in the local blockstore. If bs.Has reports the block missing and the CID is not the hardcoded empty-directory CID (which boxo can always materialize), the command returns this error, refusing to chroot to content it cannot verify.","triggerScenarios":"Chrooting to any UnixFS directory CID that was never fetched to this node; the block existed earlier but was removed by garbage collection; a typo in the CID that resolves to a different, unfetched node.","commonSituations":"Following documentation/examples that use CIDs from another machine; after `ipfs repo gc` pruned unpinned blocks; running chroot on a fresh node whose blockstore only holds the empty dir.","solutions":["Run `ipfs block get <cid>` while the daemon is running to fetch and store the block locally, then retry chroot.","Pin the target CID first so GC cannot remove it again (`ipfs pin add <cid>` before stopping the daemon).","Use the empty-directory CID (or omit the argument) if the intent is to reset to an empty root."],"exampleFix":"# before\nipfs files chroot --confirm bafybei...   # not in blockstore\n# after\nipfs pin add bafybei...        # with daemon running; also fetches\nipfs shutdown\nipfs files chroot --confirm bafybei...","handlingStrategy":"fallback","validationCode":"ipfs block stat \"$CID\" 2>/dev/null || echo \"block not local; fetch with: ipfs block get $CID\"","typeGuard":null,"tryCatchPattern":"if out, err := run(\"ipfs\",\"files\",\"chroot\",\"--confirm\",cid); err != nil && strings.Contains(out, \"does not exist locally\") {\n    run(\"ipfs\",\"block\",\"get\",cid)\n    err = run(\"ipfs\",\"files\",\"chroot\",\"--confirm\",cid)\n}","preventionTips":["Pin the target root before GC can evict it","Run `ipfs block get <cid>` as an explicit pre-fetch step in automation","On fresh nodes, remember only the empty dir is guaranteed present"],"tags":["blockstore","cid","garbage-collection","cli"],"backgroundTag":"root-block-missing-locally","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"}