{"record":{"id":"323712fc6a83e721","repo":"ipfs/kubo","slug":"either-the-filestore-or-the-urlstore-must-be-enabl","errorCode":null,"errorMessage":"either the filestore or the urlstore must be enabled to use nocopy, see: https://github.com/ipfs/kubo/blob/master/docs/experimental-features.md#ipfs-filestore","messagePattern":"either the filestore or the urlstore must be enabled to use nocopy, see: https://github\\.com/ipfs/kubo/blob/master/docs/experimental-features\\.md#ipfs-filestore","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreapi/unixfs.go","lineNumber":86,"sourceCode":"\t\tattribute.Bool(\"silent\", settings.Silent),\n\t\tattribute.Bool(\"progress\", settings.Progress),\n\t)\n\n\tcfg, err := api.repo.Config()\n\tif err != nil {\n\t\treturn path.ImmutablePath{}, err\n\t}\n\n\t// check if repo will exceed storage limit if added\n\t// TODO: this doesn't handle the case if the hashed file is already in blocks (deduplicated)\n\t// TODO: conditional GC is disabled due to it is somehow not possible to pass the size to the daemon\n\t//if err := corerepo.ConditionalGC(req.Context(), n, uint64(size)); err != nil {\n\t//\tres.SetError(err, cmds.ErrNormal)\n\t//\treturn\n\t//}\n\n\tif settings.NoCopy && !(cfg.Experimental.FilestoreEnabled || cfg.Experimental.UrlstoreEnabled) {\n\t\treturn path.ImmutablePath{}, errors.New(\"either the filestore or the urlstore must be enabled to use nocopy, see: https://github.com/ipfs/kubo/blob/master/docs/experimental-features.md#ipfs-filestore\")\n\t}\n\n\taddblockstore := api.blockstore\n\tif !(settings.FsCache || settings.NoCopy) {\n\t\taddblockstore = bstore.NewGCBlockstore(api.baseBlocks, api.blockstore)\n\t}\n\texch := api.exchange\n\tpinning := api.pinning\n\n\tif settings.OnlyHash {\n\t\t// setup a /dev/null pipeline to simulate adding the data\n\t\tdstore := dssync.MutexWrap(ds.NewNullDatastore())\n\t\tbs := bstore.NewBlockstore(dstore, bstore.WriteThrough(true)) // we use NewNullDatastore, so ok to always WriteThrough when OnlyHash\n\t\taddblockstore = bstore.NewGCBlockstore(bs, nil)               // gclocker will never be used\n\t\texch = nil                                                    // exchange will never be used\n\t\tpinning = nil                                                 // pinner will never be used\n\t}\n","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreapi/unixfs.go#L68-L104","documentation":"Add with NoCopy=true imports files without copying bytes into the blockstore, which requires the filestore or urlstore backends that reference external files in place. Both are experimental and disabled by default, so Add refuses the NoCopy option when neither is enabled.","triggerScenarios":"Calling Unixfs().Add (or `ipfs add --nocopy`) with settings.NoCopy=true while cfg.Experimental.FilestoreEnabled and UrlstoreEnabled are both false — the default configuration.","commonSituations":"Users importing large local files with --nocopy on a stock node, library code setting NoCopy assuming the filestore is always available, and DAGs migrated between nodes where the new node lacks the experimental flags.","solutions":["Enable the filestore: `ipfs config --json Experimental.FilestoreEnabled true` and restart the daemon.","Or enable the urlstore: `ipfs config --json Experimental.UrlstoreEnabled true`, if your sources are URLs.","Drop the NoCopy option and let the default blockstore copy the data.","See the linked experimental-features doc for caveats (file moves break the blocks)."],"exampleFix":"// before\nipfs add --nocopy bigfile.iso\n// after\nipfs config --json Experimental.FilestoreEnabled true && ipfs daemon\nipfs add --nocopy bigfile.iso","handlingStrategy":"validation","validationCode":"if useNoCopy {\n\tcfg, err := api.repoConfig()\n\tif err != nil {\n\t\treturn err\n\t}\n\tif !cfg.Experimental.FilestoreEnabled && !cfg.Experimental.UrlstoreEnabled {\n\t\treturn errors.New(\"nocopy requires FilestoreEnabled or UrlstoreEnabled in config\")\n\t}\n}","typeGuard":null,"tryCatchPattern":"p, err := api.Unixfs().Add(ctx, file, opts...)\nif err != nil && strings.Contains(err.Error(), \"filestore or the urlstore must be enabled\") {\n\t// retry without nocopy\n\topts = slices.DeleteFunc(opts, isNoCopyOption)\n\tp, err = api.Unixfs().Add(ctx, file, opts...)\n}","preventionTips":["Enable the filestore/urlstore in provisioning before using --nocopy","Gate NoCopy usage on a config check at application startup","Do not move/rename source files after a nocopy add — references break"],"tags":["ipfs","add","filestore","experimental-feature","config"],"backgroundTag":"feature-not-enabled","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"}