• Share a link to this article:

Troubleshooting common RapidWeaver problems

This knowledgebase article deals with identifying common problems in RapidWeaver (which may prevent RapidWeaver or your website functioning correctly) and attempts to provide general advice on resolving these issues.

Please remember that RapidWeaver is developed by Realmac Software; not ThemeFlood. Therefore if you encounter issues not discussed in this article or you are unable to resolve a particular issue, please escalate your case to Realmac Software or ask on the community forums for help.

Publishing problems

If you've recently switched to using ThemeFlood themes or made other significant changes to your website, you may find that the physical pages and content of the site get published, but styling and images are missing. You might find your browser console is listing lots of missing files, as picture below.

Missing files

Very often if you are seeing a difference between the offline and online versions of your website, this indicates that the website has not fully uploaded.

The first thing to check is that your publishing settings in RapidWeaver are correct. Carefully scrutinise your settings to ensure the website address and publishing path are correct.

The second thing to try is to Mark All Pages as Changed from the RapidWeaver File menu. Then click the Re-Publish All Files option in the RapidWeaver File menu.

Republish all files

This action will force RapidWeaver to republish the entire website again. It may take a while, but should hopefully solve any publishing issues you were having.

More serious publishing problems (like an inability to start or complete a publishing session) are most likely attributed to publishing settings being incorrect or a fault on the web server you are trying to upload the files to. This is particularly true if you're seeing errors relating to things like 'failed to create remote directory'. In these instances, it's best to contact the web hosting company for help and tell them what settings you are using.

Published changes not showing

In instances where publishing seems to happen without any incident (no error messages) but the changes do not show, this could be one of three potential issues:

  1. Refresh your web browser to make sure you are seeing the latest version of a webpage. Some web browsers (like Safari) have quite strong caching and may still be showing you an older version of a page.
  2. If your website makes use of Cloudflare, then you may need to login to your Cloudflare account and purge (delete) the cache to see all website changes (especially CSS and javascript changes).
  3. Is the website being published to the correct location? Most websites need to live inside a /public_html/ or /htdocs/ directory on your server. If the publishing path in your settings is wrong, the website may still get punished, but might be in the wrong location on the web server.

RapidWeaver 5 fails to publish a website every time

A longstanding bug in RapidWeaver 5 would sometimes cause publishing to fail every time, if you had not saved the FTP details as a bookmark. You can read many documented cases about this on the RapidWeaver forums. If you are using RapidWeaver 5 and constantly hitting publishing problems, try saving your server settings as a bookmark in the RapidWeaver publishing window. For some users, this simple action resolved publishing errors permanently.

Publishing taking a very long time to complete

Unless major changes happen to every page in your website, RapidWeaver should only publish what has changed and leave unchanged pages alone. This feature is often known as smart publishing. You should always have smart publishing enabled in RapidWeaver > Preferences > Advanced. Smart publishing will ensure smaller website changes are published more quickly.

Large resources (known as assets in older versions of RapidWeaver) cab have a detrimental effect on publishing times. it is wise to avoid adding large PDF documents, images or video files as resources. Instead you can create a new directory on your web server (call it something like website-resources) and upload your bigger files to this directory using FTP. Then you can easily link to your files and reuse them in your RapidWeaver projects:


Also of note, it is normal for publishing over SSL (https) to take longer, compared to a normal insecure (http) connection.

Font Awesome Icons missing, slow loading pages and broken pages in Internet Explorer

ThemeFlood themes are intended to be setup and published with CSS Consolidation enabled. CSS Consolidation merges multiple CSS files into singular files. This process can improve page loading speed and resolve several longstanding issues; including missing font icons or embedded web font faces and Internet Explorer compatibility problems. Always have CSS consolidation enabled in your RapidWeaver projects.

CSS consolidation and compression was added in RapidWeaver 5, and can be located in the Publishing tab of the RapidWeaver Preferences window (pictured below).

RapidWeaver 5 CSS compression and consolidation

By default, CSS consolidation should already be turned on. If you find that CSS consolidation is not turned on, then you should switch it on right now. CSS compression in RapidWeaver 5 is optional (this feature was removed in RapidWeaver 6).

In RapidWeaver 6, CSS consolidation settings can be toggled on and off on a project-by-project basis. These settings can be accessed by opening the Site Settings and clicking on the Advanced tab in the sidebar, pictured below.

RapidWeaver 6

The setup is similar in RapidWeaver 7 too. What CSS consolidation does is to amalgamate multiple theme stylesheets into just two – one dealing with screen styles and another handling your printer styles. Normally every RapidWeaver theme style setting will add a new stylesheet to a page, so in some themes the number of stylesheets can mount up dramatically. Most importantly, this means that with CSS consolidation turned on, you safely avoid the strict 28 stylesheet limit that Internet Explorer imposes on all websites (if you surpass this limit, then your page design will start falling apart when viewed through Internet Explorer). CSS consolidation can also make a noticeable improvement to the speed at which your pages load, because the web browser is making far less HTTP requests and therefore is requiring less bandwidth and files to render each page.

Range or Index Out of Bounds

This somewhat cryptic error message can occur for one of several possible reasons. It can occur at any time, such as previewing a page, exporting, saving or publishing. Some users have found that turning off CSS Consolidation will fix the problem short-term. However this is by no-means a longterm or reliable fix and the issue will still prevail below the surface and can occur again. Of course turning off CSS Consolidation carries major compatibility and performance implications of its own. So it's always best to discount CSS consolidation from the equation and fix the problem correctly and fully.

RapidWeaver range or index out of bounds

There are several things you can try:

  • Ensure that all RapidWeaver plugins you have installed are the latest versions. This is particularly true of plugins like PlusKit and Stacks. Don't rely solely on auto-updaters; instead compare your version number with the version number shown on the website.Download and apply all updates available.

  • Uninstall and delete old or obsolete RapidWeaver addons. Typically anything that has not been updated in the last two years should be considered obsolete. The only exception to this rule is if the developer states on the website that the addon has been tested and confirmed to work with your exact version of RapidWeaver or can provide verbal assurances of such.

  • Try deleting RapidWeaver from your system Applications folder. Then re-download and install RapidWeaver again. All addons and sandwich files should be safe, because these are stored elsewhere on your computer. Reinstalling wipes nearly all traces of RapidWeaver off your system and installs it from fresh. Over time, this has proven to be the most reliable way to fix the 'out of bounds' error.

  • If your website makes use of a contact form, make sure the form fields match-up to the correct attributes in the RapidWeaver Page Inspector. If for example the email subject is set to the email field, this can cause errors. Check all settings are correct and correctly match-up.

  • Use a free tool like Onyx to scan your system and fix incorrect file permissions. You should also try running daily, weekly and monthly maintenance tasks and reset caches. Onyx is safe and easy to use and can fix problems deep in your system.

  • Make sure RapidWeaver is installed in your Applications folder. This may sound really obvious, but in the past some people have tried moving the RapidWeaver app off into another location - like a mountable volume, network attached storage or a Dropbox folder. This can often result in problems occurring and is not recommended.

  • Avoid putting large files in a RapidWeaver project. High-definition images and large video's will really slow-down RapidWeaver and can make it more unstable. Big images and video should instead be warehoused and published separately to your main website. Anything over 10MB in size would be considered 'large'.

If problems persist, then you should contact Realmac Software by opening a support ticket on their website. Your message should include the exact error message or code, a copy of your RapidWeaver sandwich file, a list of installed third-party addons and details of your computer. Click Apple > About this Mac from the main menu and choose the option to view more information and save the system profile. Console logs from console.app may also be useful, as these might explain what happened immediately before the error occurred.

Random crashes and other bugs

These can occur for any number of reasons. In the event of a crash, you should get prompted to send a crash report (pictured below) which you should fill-in with your name, email and details of what happened immediately before the crash happened.

RapidWeaver crash reporter

If you get no response to your crash report after a few days, follow it up with a new support enquiry sent via the Realmac Software website. Especially if the problem is replicable or effects a certain project file. Use the same name and email address each time, so that Realmac Software can track your chain of correspondence.

Avoiding Javascript conflicts

Javascript is client-side code, which performs additional functions on a website and can be used for a wide variety of different tasks. Nearly all websites make use of Javascript in one form or another and in many instances Javascript is essential for the function of websites. ThemeFlood RapidWeaver themes are no exception, and all make use of Javascript to power different parts of the theme. Unlike server-side code, Javascript code is downloaded to the browsing computer and has to be executed (run) in a particular order. Care needs to be exercised not to 'clobber' a web browser with too much code or too many instructions!

With great power comes great responsibility; and all RapidWeaver users should take care when adding additional Javascript code to a website. Temptation aside, most expert RapidWeaver users live by the "one effect per page" rule, which basically translates towards using as fewer special effects (like animations) as possible in a page. CSS animation effects (like those found on drop-down menu's and page fade-in effects) are perfectly safe to use in multiples, as these are all hardware-accelerated. The ones to watch out for are animation effects delivered via Javascript (like slideshows, light boxes, complex animations and animated panels of content). Using too much Javascript code or too many different stack types on the same page can often result in problems. Sometimes these problems might only be restricted to a certain web browser or browser versions, making them particularly difficult to find.

So the "one effect per page" rule is certainly worth abiding by. Not only can you be assured of building more professional and less-flashy / cheesy pages, but avoid problems with browser memory leaks, security and general bugginess that might otherwise occur. Likewise you should avoid mixing different Javascript libraries together on the same page. Seek to simplify things and adopt the precautionary principle.

As mentioned already, ThemeFlood RapidWeaver themes make use of some Javascript code already. Some generic code is used to power plugins like the album page styles. We also use some jQuery Javascript code to power things like ExtraContent, freestyle banners, navigation structures, toggle effects and some other minor aspects (depending on the theme used). The Bootstrap toolkit also has some dependancies on Javascript; for things like accordions, drop-downs, modals, popovers and tooltips.

All jQuery code used in ThemeFlood RapidWeaver themes is fully scoped and name-spaced. This means that under normal circumstances, our code runs full-time in 'no conflict mode' and no other (properly written) Javascript addons are able to use our jQuery calls or conflict with the theme code. This works most of the time, but ultimately it relies on the other party to equally be running in no-conflict mode and take precautions of their own to avoid problems. In a modular setup like RapidWeaver, that is not always easy to achieve and we can't control the quality of what other developers release!

Debugging Javascript problems is very difficult. A web browser might be quite quick to flash-up an alert when problems arise; but too often the exact line of code causing the problem is much deeper than what the browser console might suggest. Unlike CSS, we cannot easily override or 'patch' buggy Javascript code. The success rate of resolving Javascript conflicts in RapidWeaver (like other publishing platforms) is pretty low. So if problems arise, it's often easier to try an omit the item that is causing the problem. This might mean rethinking how a page is built or editing the theme to remove surplus elements like bootstrap.js, if these are not required.

Form responses not being sent through the RapidWeaver contact form

The contact form page type is a page type supplied with RapidWeaver. It's functionality is not dependant on any particular RapidWeaver theme. A theme will only apply styling to the RapidWeaver contact form. Sometimes you might find that messages sent through the contact form are not received. This can happen for any number of potential reasons.

  • Check that the email address used to receive contact form submissions is correct and is functioning
  • Ensure the mailbox limit has not been exceeded for the email address
  • Login to the email account and make sure contact form submissions are not being filtered into a spam or junk mail folder
  • Some web hosting companies (like GoDaddy) only permit you to send form messages to the same email address you use to login to your web hosting account with
  • Ask your web hosting company to check that your web hosting account is running a standard version of PHP and that they are running the latest version of PHP possible, that the web server can support. Never use a web server that still uses any obsolete or unsupported versions of PHP
  • Contact the web hosting company and ask them to make sure check your MX records and email forwarder settings are correct
  • Ask the web hosting company to check the PHP error logs for any errors that might be relevant to the sending of email messages

You should always periodically check that your RapidWeaver contact forms are functioning. It's wise to send a test message every month to yourself. If you suddenly stop receiving messages, test your contact form to make sure it is working correctly. It is also recommended practice to provide other methods of contact for your website users, and not rely solely on the RapidWeaver contact form.

Missing icons and links

If you're finding that all links and icons on on a webpage are broken, make sure they've been configured correctly within RapidWeaver and ensure that CSS consolidation is enabled.

If certain links or icons on a webpage are failing to display in some web browsers (but not others), this might indicate they are being blocked. You should check the settings of any installed ad-blockers or similar software to ensure no page content is being prevented from displaying.