ipfs/kubo · error

new root must be a directory, got %s

Error message

new root must be a directory, got %s

What it means

Final type check in the root-replacement validation: the block is a valid UnixFS node but its type is neither TDirectory nor THAMTShard (e.g. a raw file or a symlink), so it cannot serve as the MFS root. The actual node type is interpolated into the message; no state has been modified.

Source

Thrown at core/commands/files.go:1795

			}
		}

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

		// Write new root
		err = localDS.Put(req.Context, node.FilesRootDatastoreKey, newRootCid.Bytes())
		if err != nil {

View on GitHub (pinned to 329838acdf)

Solutions

1. Provide the CID of a UnixFS directory (or HAMT-sharded directory) instead of a file, e.g. the root of `ipfs add -r <folder>`.
2. If a file was intended, place it under a directory and use that directory's CID as the new root.

When it happens

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