What causes "CIFS username/ak is required" in juicedata/juicefs?

Supply a valid SMB username as the access-key parameter of the cifs storage URI.

CIFS username/ak is required

Error message

CIFS username/ak is required

What it means

newCifs requires a username (mapped to the access-key parameter). CIFS/SMB authentication needs a user identity for the session setup; an empty username means the client cannot authenticate to the share, so construction fails immediately after endpoint parsing.

Source

Thrown at pkg/object/cifs.go:510

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

	if password == "" {
		return nil, fmt.Errorf("CIFS password/sk is required")
	}

	maxPool := 8
	if v := os.Getenv("JFS_CIFS_MAX_POOL"); v != "" {
		if n, err := strconv.Atoi(v); err == nil {
			maxPool = n
		}
	}

	store := &cifsStore{
		host:            host,
		port:            port,
		share:           share,
		user:            username,

View on GitHub (pinned to c9a67b23e8)

Solutions

Supply a valid SMB username as the access-key parameter of the cifs storage URI.
If the share allows guest access, still provide the guest username (often "guest" or "nobody").
Check that the access-key env/config field is populated before invoking newCifs.

Example fix

// before
newCifs("cifs://server/share", "", "secret")
// after
newCifs("cifs://server/share", "smbuser", "secret")

Defensive patterns

Strategy: validation

Validate before calling

if ak == "" {
    return fmt.Errorf("cifs storage requires a username (access key); got empty value")
}

Try / catch

obj, err := object.CreateStorage("cifs", endpoint, ak, sk, "")
if err != nil && strings.Contains(err.Error(), "username/ak is required") {
    return fmt.Errorf("missing SMB credentials: set access key to the SMB username")
}

Prevention

Always populate the access-key field for cifs URIs, even for guest shares
Validate credentials exist before constructing storage in startup code
Watch for CI secret injection producing empty strings

When it happens

Trigger: Calling newCifs(endpoint, "", password, _) — e.g. object storage URI with missing access key part, or TestCifs/TestCifs2 variants passing an empty username.

Common situations: Guest/anonymous shares where the user omitted credentials assuming they are optional; environment variables or config where the access-key field was not set; credential management systems dropping empty values.

Related errors

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