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

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 facilitate background processing, it is essential for the site to have the capability to send a POST request to its Admin Ajax URL, by utilizing the WordPress HTTP API. This action serves the purpose of initiating the processing of any pending tasks that have been queued.

To verify if your site supports background processing, go to the Tools > Site Health page within WordPress Admin and make sure the following tests pass:

• Scheduled events are running
• HTTP requests seem to be working as expected
• Your site can perform loopback requests

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 the publication stalls due to a timeout, it’s likely Staatic couldn’t adjust the PHP time limit. This issue might arise from server constraints or elements like PHP-FPM, web servers, and load balancers. To resolve, consider raising these limits or reducing the Publication Task Timeout.

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

You can also opt for the WP-CLI Publish Command. This command executes the publication using a singular PHP process, unlike the web-based publisher. Often, the command-line presents fewer constraints.

UNIX ulimit settings

UNIX-based systems, including Linux and macOS, provide tools to monitor and control the use of resources such as threads, files, and network connections for each process and user. The “ulimits” function ensures that individual users don’t overconsume these resources. However, if these limits are set too low by default, Staatic may face operational challenges. However, low default values of these limits may lead to various issues during the regular operation of Staatic.

A crucial parameter to watch is the “Number of open files” limit. It’s typically set at a default of 1,024. Given the themes, plugins, and customizations of your site, this default can be quickly surpassed. For smoother operation, we suggest adjusting this limit to a minimum of 4,096.

Note: when limits are exceeded, this can lead to the occurrence of seemingly random errors, such as those associated with non-existent PHP classes.

Publication takes too long

To generate the static version of your WordPress site, Staatic follows the same process as a regular visitor. However, this can be time-consuming, particularly when there are numerous pages and assets to process, and the server resources are limited. The involvement of WordPress, PHP, and the database during content generation contributes to the overall time taken.

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. Nevertheless, additional manual optimization might be necessary.

Below are key areas you might consider optimizing:

Deactivate unused plugins

Disabling unnecessary plugins can reduce the utilization of server resources, resulting in improved crawling speed.

Decrease logging verbosity

It is recommended to set the Logging setting to either Minimal Logging or No Logging during normal operations. Increasing the verbosity level consumes more server resources and should be limited to troubleshooting sessions only.

Tune HTTP concurrency

HTTP concurrency refers to the number of pages that are crawled simultaneously. Adjusting the HTTP concurrency setting to your server’s available resources can help optimize the crawl rate.

Note: Always monitor the server’s CPU and memory usage when adjusting the HTTP concurrency. Overloading the server by setting an excessively high concurrency value can lead to request failures and HTTP 5xx responses. Such issues might negatively impact the final 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.