juicedata/juicefs · error

endpoint should be a valid share name (%s)

Error message

endpoint should be a valid share name (%s)

What it means

After parsing the endpoint URL, parseEndpoint requires the URL path to name exactly one share (u.Path must have a non-empty first segment and nothing after it). If the path is empty (len(parts) < 2) or parts[1] is empty, there is no share name, so the CIFS backend cannot be constructed.

Source

Thrown at pkg/object/cifs.go:493

		endpoint = "cifs://" + endpoint
	}
	u, err := url.Parse(endpoint)
	if err != nil {
		return
	}
	if u.Scheme != "" && (u.Scheme != "cifs" && u.Scheme != "smb") {
		err = fmt.Errorf("invalid scheme %s, should be cifs:// or smb://", u.Scheme)
		return
	}

	host = u.Hostname()
	port = u.Port()
	if port == "" {
		port = "445" // Default SMB port
	}
	parts := strings.Split(u.Path, "/")
	if len(parts) < 2 || parts[1] == "" {
		err = fmt.Errorf("endpoint should be a valid share name (%s)", "\\\\<server>\\<share>")
		return
	}
	if len(parts) > 2 && parts[2] != "" {
		err = fmt.Errorf("endpoint should be a valid share name (%s)", "\\\\<server>\\<share>")
		return
	}
	share = parts[1]
	return
}

func newCifs(endpoint, username, password, _ string) (ObjectStorage, error) {
	host, port, share, err := parseEndpoint(endpoint)
	if err != nil {
		return nil, err
	}
	if username == "" {
		return nil, fmt.Errorf("CIFS username/ak is required")
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Append the share name to the endpoint: "cifs://server/share" (or \\<server>\\share).
2. Ensure the share segment is non-empty, not just a trailing slash.
3. Check the config file/URI for accidental truncation of the share name.

Example fix

// before
newCifs("cifs://fileserver", ...)
// after
newCifs("cifs://fileserver/myshare", ...)

u, _ := url.Parse(endpoint)
share := strings.SplitN(u.Path, "/", 3)
if len(share) < 2 || share[1] == "" {
    return fmt.Errorf("endpoint must include a share: cifs://server/share")
}

func hasShareName(endpoint string) bool {
    u, err := url.Parse(endpoint)
    if err != nil { return false }
    parts := strings.Split(u.Path, "/")
    return len(parts) >= 2 && parts[1] != ""
}

obj, err := object.CreateStorage("cifs", endpoint, ak, sk, "")
if err != nil && strings.Contains(err.Error(), "valid share name") {
    endpoint = fmt.Sprintf("cifs://%s/share", host) // append default share and retry
}

When it happens

Trigger: Endpoints like "cifs://server", "cifs://server/", "cifs://server" with no path, or \\<server> with no share component passed to newCifs.

Common situations: User configured only the server address without the share; trimmed/lost the share part when templating config; forgot that CIFS endpoints must always include the share.

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

• invalid scheme %s, should be cifs:// or smb://
• Invalid endpoint: %v, error: %v
• SMB authentication failed: %v
• failed to mount SMB share %s: %v
• CIFS username/ak is required

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