What causes "failure writing filesroot to dagstore: %s" in ipfs/kubo?

Check disk space and writability of IPFS_PATH: `df -h $IPFS_PATH` and try creating a file in the repo directory.

failure writing filesroot to dagstore: %s

Error message

failure writing filesroot to dagstore: %s

What it means

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".

Source

Thrown at core/node/core.go:232

				return err
			}

			if err := rootDS.Put(ctx, FilesRootDatastoreKey, c.Bytes()); err != nil {
				return err
			}
			return rootDS.Sync(ctx, FilesRootDatastoreKey)
		}

		var nd *merkledag.ProtoNode
		ctx := helpers.LifecycleCtx(mctx, lc)
		val, err := repo.Datastore().Get(ctx, FilesRootDatastoreKey)

		switch {
		case errors.Is(err, datastore.ErrNotFound):
			nd = unixfs.EmptyDirNode()
			err := dag.Add(ctx, nd)
			if err != nil {
				return nil, fmt.Errorf("failure writing filesroot to dagstore: %s", err)
			}
		case err == nil:
			c, err := cid.Cast(val)
			if err != nil {
				return nil, err
			}

			offlineDag := merkledag.NewDAGService(blockservice.New(bs, offline.Exchange(bs)))
			rnd, err := offlineDag.Get(ctx, c)
			if err != nil {
				return nil, fmt.Errorf("error loading filesroot from dagservice: %s", err)
			}

			pbnd, ok := rnd.(*merkledag.ProtoNode)
			if !ok {
				return nil, merkledag.ErrNotProtobuf
			}

View on GitHub (pinned to 329838acdf)

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.

Defensive patterns

Strategy: validation

Validate before calling

# Before starting the daemon, verify the repo is writable and has space
test -w "$IPFS_PATH" && echo writable || echo "repo not writable"
df -h "$IPFS_PATH" | awk 'NR==2 {print "free:", $4}'

Try / catch

// When driving node construction programmatically
if _, err := nodeStartup(ctx); err != nil {
    var dsErr error
    if errors.As(err, &dsErr) && errors.Is(err, context.Canceled) {
        // startup was cancelled; retry with a fresh lifecycle context
    }
    return fmt.Errorf("node startup failed at filesroot init: %w", err)
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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