juicedata/juicefs · error

unable to mount %s: %v

Error message

unable to mount %s: %v

What it means

newNFSStore mounts a local directory over an in-process NFS server (github.com/willscott/go-nfs) so JuiceFS can treat it as object storage. After Mount() returns an error, the wrapper is wrapped with 'unable to mount <addr>' so the caller knows which NFS address/path failed. Any failure inside the go-nfs Mount handshake (filesystem backend errors, connection setup) surfaces here.

Source

Thrown at pkg/object/nfs.go:482

		username = u.Username
	}
	b := strings.Split(addr, ":")
	if len(b) != 2 {
		return nil, fmt.Errorf("invalid NFS address %s", addr)
	}
	host := b[0]
	path := b[1]
	mount, err := nfs.DialMount(host, time.Second*3)
	if err != nil {
		return nil, fmt.Errorf("unable to dial MOUNT service %s: %v", addr, err)
	}
	auth := rpc.NewAuthUnix(username, uint32(utils.GetCurrentUID()), uint32(utils.GetCurrentGID()))
	target, err := mount.Mount(path, auth.Auth())
	target.Config.DirCount = 1 << 17
	// Readdir returns up to 1M at a time, even if MaxCount is set larger
	target.Config.MaxCount = 1 << 20
	if err != nil {
		return nil, fmt.Errorf("unable to mount %s: %v", addr, err)
	}
	umask := utils.GetUmask()
	return &nfsStore{
		username: username,
		host:     host,
		root:     path,
		fmode:    os.FileMode(0666 &^ umask),
		dmode:    os.FileMode(0777 &^ umask),
		target:   target}, nil
}

func init() {
	Register("nfs", newNFSStore)
}

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Check the wrapped %v error to see the underlying go-nfs failure and fix the path/permissions it names
  2. Verify the path exists and the current user (GetCurrentUID/GID) can read it
  3. Ensure the path is an absolute directory suitable for the NFS backend
  4. Retry after fixing; re-check go-nfs dependency version if the error is internal to the library

Example fix

// before
store, err := object.CreateStorage("nfs", "/data/export", "", "", "")
// after
if _, err := os.Stat("/data/export"); err != nil {
	log.Fatalf("NFS export path missing: %v", err)
}
store, err := object.CreateStorage("nfs", "/data/export", "", "", "")
if err != nil {
	log.Fatalf("unable to mount nfs: %v", err)
}
Defensive patterns

Strategy: try-catch

Validate before calling

if _, err := os.Stat(nfsPath); err != nil { return fmt.Errorf("nfs path check: %w", err) }

Try / catch

store, err := object.CreateStorage("nfs", path, "", "", "")
if err != nil && strings.Contains(err.Error(), "unable to mount") {
	// inspect wrapped cause, fix path/permissions, retry
}

Prevention

When it happens

Trigger: Calling CreateStorage("nfs", ...) or mounting an NFS-style URL where the underlying nfsutil/filesystem backend cannot serve the target path, or mount.Mount returns an error for the given path/auth.

Common situations: Source path does not exist or is not accessible by the client user; UID/GID mismatch between the JuiceFS process and the path permissions; unsupported or broken path (e.g. symlink issues); go-nfs library version incompatible with the path type.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/ea1ec087ec3c73fc. Report an issue: GitHub.