Troubleshooting

• Introduction
• Publication issues
  • Publication does not start
  • Publication fails or does not finish
  • Publication takes too long

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 does not start

If you are starting a publication using the Publish, Publish Changes or Publish Everything actions within the WordPress Admin, and the publication status is stuck at “Preparing publication”, this typically indicates one or both of the following issues:

1) Staatic is unable to reach your site internally over HTTP(S).
2) WP-Cron is disabled or not running.

In order for the publication process to work, Staatic relies on a background processing library that enables it to execute the potentially long-running publication process in the background, in order to circumvent server restrictions such as memory and time limits. The publication process is distributed into many smaller jobs that are sequentially executed and potentially restarted using WP-Cron.

Verify internal HTTP(S) connectivity

In order to verify the internal connectivity of your WordPress site, head over to WordPress Admin and click Staatic > Settings. On the welcome page, if you are seeing Configuration Issues (just above the Support heading), and the reported issues include “Staatic is unable to access your WordPress site”, something is preventing internal connectivity.

Note: it may take up to a minute for the Configuration Issues to be displayed.

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.

Verify that WP-Cron is working

In order to test the WP-Cron spawning system using WP-CLI, run the wp cron test command:

$ wp cron test
Success: WP-Cron spawning is working as expected.

Testing WP-Cron from within WordPress Admin is not possible without a plugin.

One plugin that allows you to do so is WP Crontrol. Once installed, you can locate all cron jobs under Tools > Cron Events. The “next run” column provides an insight into their status, and it should show no jobs with a past date.

Publication fails or does not finish

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.

Fatal errors

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.

Time-outs

If a time-out has caused the publication to hang, Staatic might have been unable to increase the PHP time limit. This could be due to server restrictions, or other components involved like PHP-FPM, web servers and load balancers. In that case, you can either increase these limits, or decrease the Publication Task Timeout setting.

This is an overview of some of the relevant configuration values:

Alternatively, it is possible to use the WP-CLI Publish Command. This command runs the publication from a single PHP process, as opposed to the web-based publisher. Many times, there are fewer restrictions when running from the command-line.

UNIX ulimit settings

UNIX-like operating systems, such as Linux and macOS, offer tools to regulate and manage the consumption of system resources like threads, files, and network connections for each process and user. The usage of “ulimits” helps in avoiding excessive consumption of system resources by individual users. However, low default values of these limits may lead to various issues during the regular operation of Staatic.

One specifically important limit is the “Number of open files” limit, which by default is set relatively low (1,024) and can be easily exceeded depending on your site’s theme, plugins and customizations. We recommend increasing this limit to at least 4,096.

Publication takes too long

In order to generate the static version of your WordPress site, Staatic visits every page in 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, when generating the requested content, WordPress, PHP and the database are still involved.

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.