ipfs/kubo · error

new root is not a valid UnixFS node: %w

Error message

new root is not a valid UnixFS node: %w

What it means

Next validation step for the new MFS root: the block decoded as dag-pb, but ft.FSNodeFromBytes rejected its embedded data, so the node is dag-pb yet not a UnixFS directory (e.g. a plain dag-pb node without UnixFS metadata). The root replacement stops before writing anything.

Source

Thrown at core/commands/files.go:1792

			emptyDirCid := ft.EmptyDirNode().Cid()
			if !newRootCid.Equals(emptyDirCid) {
				return fmt.Errorf("new root %s does not exist locally; fetch it first with 'ipfs block get'", enc.Encode(newRootCid))
			}
		}

		// Validate it's a directory (not a file)
		if hasBlock {
			blk, err := bs.Get(req.Context, newRootCid)
			if err != nil {
				return fmt.Errorf("reading new root block: %w", err)
			}
			pbNode, err := dag.DecodeProtobuf(blk.RawData())
			if err != nil {
				return fmt.Errorf("new root is not a valid dag-pb node: %w", err)
			}
			fsNode, err := ft.FSNodeFromBytes(pbNode.Data())
			if err != nil {
				return fmt.Errorf("new root is not a valid UnixFS node: %w", err)
			}
			if fsNode.Type() != ft.TDirectory && fsNode.Type() != ft.THAMTShard {
				return fmt.Errorf("new root must be a directory, got %s", fsNode.Type())
			}
		}

		// 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)
		}

View on GitHub (pinned to 329838acdf)

Solutions

1. Use a CID produced by UnixFS directory construction (`ipfs add` of a folder or MFS flush), not arbitrary dag-pb data.
2. Check the block with `ipfs dag get <cid>` to see its actual structure before retrying.

When it happens

Trigger: Thrown at core/commands/files.go:1792 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/cdcddf0cdcffae59. Report an issue: GitHub.