Documentation / Setting up Staatic / Troubleshooting

Troubleshooting

Introduction

The topics in this article explain how to determine, diagnose, and fix issues that you might encounter when you use Staatic for WordPress.

Publication issues

Publication fails or does not finish

There are a number of reasons that can cause a publication to fail or prevent it from finishing. Here is an overview of the most common reasons.

Staatic is unable to crawl your site

When crawling the dynamic version of your WordPress site, Staatic acts in the same way as any other regular visitor by requesting the pages from your server using HTTP or HTTPS. In order to do so successfully, Staatic needs access to your dynamic site.

In case you are restricting access by visitor IP, either using a .htaccess file or similar, or a plugin like Restricted Site Access, make sure that the server’s IP address is accepted, e.g. 127.0.0.1 or your server’s primary IP.

When you are using HTTP basic authentication to restrict access to your dynamic site, make sure to enter the basic authentication credentials in the plugin’s settings.

During the crawling process the publication hangs

The most common reason for a publication to hang is a fatal error or time-out during the publication process, which the plugin was not able to handle gracefully.

To determine if an error is the cause of the publication hanging, you can temporarily enable WP_DEBUG and WP_DEBUG_LOG. This can be done be adding these lines to your wp-config.php configuration file, see also Debugging in WordPress:

define ( 'WP_DEBUG', true );
define ( 'WP_DEBUG_LOG', true );

After having started a new publication and waiting for the publication to hang, you should be able to find the following file in your WordPress installation: wp-content/debug.log. If an error is causing the hang, it should be visible within this file.

Note: make sure to disable WP_DEBUG mode afterwards, in order to prevent sensitive details leaking into the static version of your site.

If a time-out caused the publication to hang, your host might be restricting the ability to increase the PHP max_execution_time. Even though Staatic tries to circumvent such limitations automatically, your site might be too large for the server to handle the publication process. In that case consult with your host to remove the restriction or try publishing from a different server.

Alternatively, it is possible to use WP-CLI Publish Command. This command runs the publication from a single PHP process, as opposed to the web-based publisher, which uses the WP Background Processing library to work around time-out issues. In many cases restrictions are less tight when running from the command-line.

Publication takes too long

In order to generate the static version of your WordPress site, Staatic visits every page the same way a normal visitor would. This can take a long time, depending on the amount of pages and assets, and depending on available server resources. This is because WordPress, PHP and the database are involved when generating the requested content.

The crawler process has been optimized as much as possible to limit the time necessary (especially when using our Staatic Cloud offering) and a quick-publish feature is available to publish only the content that has changed since the last publication. However, further manual optimization may be needed.

Here is an overview of some of the things that could be checked.

Deactivate unused plugins

Deactivating plugins that are no longer needed reduces the amount of server resources utilized, improving the crawling speed.

Decrease logging verbosity

It is recommended to set the Logging setting to either Minimal Logging or No Logging during normal operations. A higher verbosity increases server resource usage and should only be used during troubleshooting sessions.

Tune HTTP concurrency

Depending on the available server resources, it is possible to experiment with the HTTP concurrency setting. This allows multiple pages to be crawled concurrently.

Note: It is recommended to monitor CPU/memory usage while running a publication with a higher HTTP concurrency. If the HTTP concurrency is set too high, requests may fail and result in HTTP 5xx responses, which will become part of the generated static site.

Symlink uploads

When using the Local Directory deployment method, and running on in Linux environment, it is recommended to enable the Symlink/Copy Uploads setting.

By doing so, during the publication process a symlink is created for the wp-content/uploads directory. This ensures that all content of the uploads directory is available on the static site, without the need to crawl and process each individual file, greatly reducing the publication time.