What causes "invalid NFS address %s" in juicedata/juicefs?

Use the standard 'host:/export/path' form, e.g. 'nfsserver:/export/data'.

invalid NFS address %s

Error message

invalid NFS address %s

What it means

newNFSStore expects the address in 'host:/export/path' form; it splits on ':' and requires exactly two parts. Any other count — missing colon, extra colons (e.g. unbracketed IPv6), or multiple path colons — yields 'invalid NFS address'.

Source

Thrown at pkg/object/nfs.go:468

		return n.findOwnerGroup(st)
	}
	if st, match := info.Sys().(*nfs.Fattr); match {
		return n.findOwnerGroup(st)
	}
	return "", ""
}

func newNFSStore(addr, username, pass, token string) (ObjectStorage, error) {
	if username == "" {
		u, err := user.Current()
		if err != nil {
			return nil, fmt.Errorf("current user: %s", err)
		}
		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,

View on GitHub (pinned to c9a67b23e8)

Solutions

Use the standard 'host:/export/path' form, e.g. 'nfsserver:/export/data'.
For IPv6 servers, use a resolvable hostname instead of a literal address, or normalize the address so exactly one colon separates host and path.
Trim whitespace and verify the endpoint contains exactly one colon.

Example fix

// before
newNFSStore("fd00::1:/export", "user", "", "")
// after
newNFSStore("nfs6.internal:/export", "user", "", "") // hostname instead of IPv6 literal

Defensive patterns

Strategy: validation

Validate before calling

if strings.Count(addr, ":") != 1 || !strings.Contains(addr, ":/") {
	return fmt.Errorf("NFS address %q must be host:/export/path", addr)
}

Try / catch

store, err := newNFSStore(addr, user, pass, "")
if err != nil && strings.Contains(err.Error(), "invalid NFS address") {
	return fmt.Errorf("use host:/path form for NFS address, got %q", addr)
}

Prevention

Use the canonical host:/export form everywhere NFS endpoints are configured.
Use hostnames instead of raw IPv6 literals to avoid extra colons.
Trim whitespace when parsing addresses from config.

When it happens

Trigger: Passing addresses like 'nfsserver' (no colon), 'host:/a:/b', or an unbracketed IPv6 address 'fd00::1:/export' to newNFSStore / an nfs:// URL.

Common situations: Omitting the export path; pasting an IPv6 NFS server address without handling the colons; trailing colon or whitespace in config.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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