{"record":{"id":"b2454a9a75ffc0a5","repo":"ipfs/kubo","slug":"failure-writing-filesroot-to-dagstore-s","errorCode":null,"errorMessage":"failure writing filesroot to dagstore: %s","messagePattern":"failure writing filesroot to dagstore: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"core/node/core.go","lineNumber":232,"sourceCode":"\t\t\t\treturn err\n\t\t\t}\n\n\t\t\tif err := rootDS.Put(ctx, FilesRootDatastoreKey, c.Bytes()); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\treturn rootDS.Sync(ctx, FilesRootDatastoreKey)\n\t\t}\n\n\t\tvar nd *merkledag.ProtoNode\n\t\tctx := helpers.LifecycleCtx(mctx, lc)\n\t\tval, err := repo.Datastore().Get(ctx, FilesRootDatastoreKey)\n\n\t\tswitch {\n\t\tcase errors.Is(err, datastore.ErrNotFound):\n\t\t\tnd = unixfs.EmptyDirNode()\n\t\t\terr := dag.Add(ctx, nd)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"failure writing filesroot to dagstore: %s\", err)\n\t\t\t}\n\t\tcase err == nil:\n\t\t\tc, err := cid.Cast(val)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}\n\n\t\t\tofflineDag := merkledag.NewDAGService(blockservice.New(bs, offline.Exchange(bs)))\n\t\t\trnd, err := offlineDag.Get(ctx, c)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"error loading filesroot from dagservice: %s\", err)\n\t\t\t}\n\n\t\t\tpbnd, ok := rnd.(*merkledag.ProtoNode)\n\t\t\tif !ok {\n\t\t\t\treturn nil, merkledag.ErrNotProtobuf\n\t\t\t}\n","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/node/core.go#L214-L250","documentation":"On daemon startup, if no MFS filesroot CID exists in the datastore yet (datastore.ErrNotFound), Kubo creates a new empty UnixFS directory and writes it via the DAGService. If that add fails (blockstore write error, datastore failure, context cancellation during startup), the error is wrapped as \"failure writing filesroot to dagstore\".","triggerScenarios":"First-ever node init where the FilesRootDatastoreKey is absent and `dag.Add(ctx, unixfs.EmptyDirNode())` fails: the underlying blockstore is unwritable (disk full, permissions), the datastore returns an I/O error, or the lifecycle context is already cancelled during startup.","commonSituations":"Fresh `ipfs init` on a disk with no free space or read-only repo directory; corrupted or locked datastore; container volumes mounted read-only; repo permission issues after running the daemon as a different user.","solutions":["Check disk space and writability of IPFS_PATH: `df -h $IPFS_PATH` and try creating a file in the repo directory.","Fix repo permissions (`chown -R` to the user running the daemon) and ensure only one daemon runs against the repo (`pkill -f \"ipfs daemon\"` first).","If the datastore is corrupt, run `ipfs repo fsck` or restore from backup; as a last resort re-init (`ipfs init`) in a new IPFS_PATH.","Re-run the daemon with GOLOG_LOG_LEVEL=debug to see the underlying datastore error."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# Before starting the daemon, verify the repo is writable and has space\ntest -w \"$IPFS_PATH\" && echo writable || echo \"repo not writable\"\ndf -h \"$IPFS_PATH\" | awk 'NR==2 {print \"free:\", $4}'","typeGuard":null,"tryCatchPattern":"// When driving node construction programmatically\nif _, err := nodeStartup(ctx); err != nil {\n    var dsErr error\n    if errors.As(err, &dsErr) && errors.Is(err, context.Canceled) {\n        // startup was cancelled; retry with a fresh lifecycle context\n    }\n    return fmt.Errorf(\"node startup failed at filesroot init: %w\", err)\n}","preventionTips":["Monitor disk space and alert before it fills; the repo writes on every startup.","Run the daemon under a dedicated user with stable ownership of IPFS_PATH.","Avoid killing the daemon during startup; use `ipfs shutdown` for graceful stop.","Never mount IPFS_PATH read-only for a writable node."],"tags":["datastore","mfs","startup","disk"],"backgroundTag":"datastore-write-failure","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"}