AlistGo/alist · error

only write in mfs mode

Error message

only write in mfs mode

What it means

Returned by IPFS driver MakeDir when Mode != "mfs". Only MFS (the mutable filesystem) supports directory creation; ipfs/ipns modes address immutable content-addressed data, so write operations are structurally impossible regardless of node permissions.

Source

Thrown at drivers/ipfs_api/driver.go:112

	case "mfs":
		fileStat, err := d.sh.FilesStat(ctx, rawPath)
		if err != nil {
			return nil, err
		}
		ipfsPath = path.Join("/ipfs", fileStat.Hash)
	default:
		return nil, fmt.Errorf("mode error")
	}
	file, err := d.sh.FilesStat(ctx, ipfsPath)
	if err != nil {
		return nil, err
	}
	return &model.Object{ID: file.Hash, Name: path.Base(rawPath), Path: rawPath, Size: int64(file.Size), IsFolder: file.Type == "directory"}, nil
}

func (d *IPFS) MakeDir(ctx context.Context, parentDir model.Obj, dirName string) (model.Obj, error) {
	if d.Mode != "mfs" {
		return nil, fmt.Errorf("only write in mfs mode")
	}
	dirPath := parentDir.GetPath()
	err := d.sh.FilesMkdir(ctx, path.Join(dirPath, dirName), shell.FilesMkdir.Parents(true))
	if err != nil {
		return nil, err
	}
	file, err := d.sh.FilesStat(ctx, path.Join(dirPath, dirName))
	if err != nil {
		return nil, err
	}
	return &model.Object{ID: file.Hash, Name: dirName, Path: path.Join(dirPath, dirName), Size: int64(file.Size), IsFolder: true}, nil
}

func (d *IPFS) Move(ctx context.Context, srcObj, dstDir model.Obj) (model.Obj, error) {
	if d.Mode != "mfs" {
		return nil, fmt.Errorf("only write in mfs mode")
	}
	dstPath := path.Join(dstDir.GetPath(), path.Base(srcObj.GetPath()))

View on GitHub (pinned to 843d9dc814)

Solutions

1. Switch Mode to "mfs" (requires a local/writable IPFS node, not a read-only gateway) if you need writes.
2. Otherwise remove write permissions for that mount in the host application so write actions are not attempted.
3. Point MakeDir-targeted workflows at a separate mfs-mode storage.

if d.Mode != "mfs" {
    return errors.New("MakeDir requires an mfs-mode storage with a writable local node")
}

func isWritableMode(mode string) bool { return mode == "mfs" }

if _, err := d.MakeDir(ctx, parent, name); err != nil && strings.Contains(err.Error(), "only write in mfs mode") {
    // route the operation to an mfs storage or surface read-only notice to the user
}

When it happens

Trigger: Mounting a CID or IPNS name read-only and attempting MakeDir; leftover write calls against a storage whose mode was switched from mfs to ipfs/ipns.

Common situations: User points the driver at a public gateway/CID for browsing, then a sync tool tries to create folders; mode changed after objects were cached, and the UI still offers write actions.

Related errors

• cannot write to non-branch reference
• mode error

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/76a685c2c784ec45. Report an issue: GitHub.