Category Archives: X-cart 5

X-cart 5 Tips: Stuck Deploying Changes?

Adding or upgrading a module to your X-cart 5 store will deploy these changes to it’s code-base. During the “deploying changes”  process, X-cart performs several additional maintenance tasks that keep your site functioning.

For example, rather than serving up the files from the main “classes” and “skins” directory, a snapshot is created. This snapshot represents the actual code that’s served to users when they request pages within your store. While it does this, it runs a series of special calculations and optimizations on that code, so that your store is a fast as possible.

Sometimes, during this process, something goes awry. During the “deploying changes” process you’ll see a text scroll of what phase of the process you’re in. When that stream stops, hangs, or throws an error something has gone wrong.

Sometimes “deploying changes” goes REALLY wrong; your entire site is down, and visitors will be greeted with the spinning gear of death…

What the store looks like to customers when deploying changes goes wrong.

When this happens, what are you supposed to do? Here’s a few tips:

Try The Back Button

X-cart 5 can be finicky at times. It’s a complex piece of software. Sometimes, deploying changes will appear to stall for no obvious reasons. When this happens to me the first thing I always try is to just jump back to the previous admin page using the back button.

Many times this will re-start the “deploying changes” process and it’ll finish with no problems whatsoever!

Delete Your Site’s Cache

If something really went wrong, you can delete the site’s current snapshot and reload. There are two ways to do this:

If you have FTP/SSH Access

Log into your store via FTP/SSH, and delete the files in the <X-Cart Directory>/var/run folder, and the file  <X-Cart Directory>/var/.rebuildStarted. Here <X-cart Directory> is the location of admin.php for your store. Then go to the admin area of your store. X-cart will detect the absence of the cache and attempt to rebuild it.

If you do NOT have SSH Access

You can access your store’s “drop cache” function at:



where <YOUR_XCART_URL> is the main page for your store, such as “” and <YOUR_SAFEMODE_KEY> is a special key that allows this functionality to be invoked. You can find the value of the key in the file var/data/.safeModeAccessKey in your X-Cart installation folder.

Last Resort: Safe Mode

Before you get into this situation, you should go to Admin > System Tools > Safe Mode to generate the various safe-mode links for your store. This will allow you one set of steps you can take when deploying changes goes wrong.

When deploying changes goes really wrong, safe mode can save you!

You can see that these links have the same structure as the “Drop Cache” link above… you can replace site URL with <YOUR_XCART_URL> and the example access key with <YOUR_SAFEMODE_KEY>as described above, and use the URLs from this image to access your store’s reset features.

It is best to try them in order, first attempting to restore the add-on’s current state. Then if that doesn’t work, try the soft reset. And, lastly, if that fails, the hard reset.

  • Restoring the Current State of All-Ons basically is a simple re-deploy. All code from the modules will be re-set, and the store will try to re-build the cache.
  • Soft Reset removes all modules except those developed by the X-cart directly. You can then go back and re-enable any custom modules using normal means.
  • Hard Reset removes all modules, except for those developed by X-cart (including custom code that X-cart has developed for you), and including those provided by the X-cart Marketplace. Your site will need some serious work re-enabling your modules one-by-one if your undertake this reset… so it’s not to be done lightly.

When All Else Has Failed…

Sometimes, you’re just in such a pickle that you’re not going to be able to get out of it yourself. When that happens, trust the experience X-cart developers at BCS Engineering to get your store back together for you quickly and easily.

Contact BCS Engineering today to find out about our many support options, including emergency support for when your store is stuck deploying changes. We’re here to help!