ipfs/kubo · error

writing new MFS root: %w

Error message

writing new MFS root: %w

What it means

The validated new root CID could not be persisted: localDS.Put of the MFS root datastore key failed (disk full, I/O error, datastore failure). All validation already passed; the failure is at the final write, so the MFS root remains unchanged unless the datastore partially persisted the put.

Source

Thrown at core/commands/files.go:1814

			}
		}

		// Get old root for display (if exists)
		var oldRootStr string
		oldRootBytes, err := localDS.Get(req.Context, node.FilesRootDatastoreKey)
		if err == nil {
			oldRootCid, err := cid.Cast(oldRootBytes)
			if err == nil {
				oldRootStr = enc.Encode(oldRootCid)
			}
		} else if !errors.Is(err, datastore.ErrNotFound) {
			return fmt.Errorf("reading current MFS root: %w", err)
		}

		// Write new root
		err = localDS.Put(req.Context, node.FilesRootDatastoreKey, newRootCid.Bytes())
		if err != nil {
			return fmt.Errorf("writing new MFS root: %w", err)
		}

		// Build output message
		newRootStr := enc.Encode(newRootCid)
		var msg string
		if oldRootStr != "" {
			msg = fmt.Sprintf("MFS root changed from %s to %s\n", oldRootStr, newRootStr)
			msg += fmt.Sprintf("The old root %s will be garbage collected unless pinned.\n", oldRootStr)
		} else {
			msg = fmt.Sprintf("MFS root set to %s\n", newRootStr)
		}

		return cmds.EmitOnce(res, &MessageOutput{Message: msg})
	},
	Type: MessageOutput{},
	Encoders: cmds.EncoderMap{
		cmds.Text: cmds.MakeTypedEncoder(func(req *cmds.Request, w io.Writer, out *MessageOutput) error {
			_, err := fmt.Fprint(w, out.Message)

View on GitHub (pinned to 329838acdf)

Solutions

1. Check free disk space and datastore health under IPFS_PATH, fix the wrapped cause, then retry the root replacement.
2. Verify the current root with `ipfs files stat /` after recovery to confirm which root is active.

When it happens

Trigger: Thrown at core/commands/files.go:1814 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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