juicedata/juicefs · error

failed to mount SMB share %s: %v

Error message

failed to mount SMB share %s: %v

What it means

After the SMB session is authenticated, getConnection mounts the configured share via session.WithContext(ctx).Mount(c.share). If the mount fails (share name wrong, share not exported, insufficient share permissions, tree-connect rejected), the connection is closed and this error is returned naming the share.

Source

Thrown at pkg/object/cifs.go:138

	// Establish SMB connection
	address := net.JoinHostPort(c.host, c.port)
	d := &smb2.Dialer{
		Initiator: &smb2.NTLMInitiator{
			User:     c.user,
			Password: c.password,
		},
	}

	var err error
	conn.session, err = d.Dial(ctx, address)
	if err != nil {
		return nil, fmt.Errorf("SMB authentication failed: %v", err)
	}

	conn.share, err = conn.session.WithContext(ctx).Mount(c.share)
	if err != nil {
		c.closeConnection(conn)
		return nil, fmt.Errorf("failed to mount SMB share %s: %v", c.share, err)
	}

	return conn, nil
}

func (c *cifsStore) closeConnection(conn *cifsConn) {
	if conn == nil || conn.session == nil {
		return
	}

	session := conn.session
	conn.session = nil
	conn.share = nil

	_ = session.WithContext(context.Background()).Logoff()
}

func (c *cifsStore) closeConnectionAsync(conn *cifsConn) {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Verify the share exists: smbclient -L //host -U user lists available shares
2. Fix the share name in the endpoint (exact name as exported by the server)
3. Grant the authenticated user share-level and filesystem-level permissions on the share
4. Check server logs for tree-connect denial reasons (access control, connection limits)

Example fix

// before
// smb://fileserver/wrongshare?username=user
// after
// smb://fileserver/public?username=user

// Shell: confirm the share exists and is accessible
smbclient -L //fileserver -U 'DOMAIN\\user' | grep -F 'public' || {
  echo "share not found"; exit 1;
}

// Go
obj, err := object.NewCifs(endpoint)
if err != nil && strings.Contains(err.Error(), "failed to mount SMB share") {
    // verify share name and share-level permissions server-side
}

When it happens

Trigger: conn.session.WithContext(ctx).Mount(c.share) errors: share does not exist on the server, share access denied for the authenticated user, typo in share name, or the server refuses tree connect (e.g. share reached connection limit).

Common situations: Share name typo (case-sensitivity on some servers); user lacks share-level ACL permission on Windows/Samba; share renamed or removed; hidden/administrative shares not accessible; too many concurrent connections per user.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• SMB authentication failed: %v
• object storage: %s
• invalid scheme %s, should be cifs:// or smb://
• endpoint should be a valid share name (%s)
• CIFS username/ak is required

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