Troubleshooting

• Where to look first
• Publication does not start
• Publication worker diagnostic
• Publication stalls or fails
• Publication takes too long
• Staatic Cloud deployment issues
• Enable WordPress debug logging
• Server limits to check

Use this page when a Staatic publication does not start, appears stuck, fails during a task, or takes longer than expected. Start with Staatic’s own status screens before changing server configuration.

Where to look first

For troubleshooting sessions, set Logging to Detailed logging or Extensive logging under Staatic > Settings > Advanced. Set it back to Minimal logging or No logging after the issue is resolved, because verbose logging can slow down publication.

Publication does not start

If the publication button appears to do nothing, or Staatic reports that another publication is pending, check these items first:

• Cancel any publication that is still marked as in progress under Staatic > Publications.
• Run Tools > Site Health and resolve Staatic’s publication worker and loopback warnings.
• If Site Health reports that the publication worker diagnostic has not been run, verify that WP-Cron and background requests can run. See Publication worker diagnostic.
• Make sure the site can make HTTP requests to itself. Firewalls, basic authentication, blocked server IPs, invalid SSL configuration, or an unreachable origin can prevent background processing and crawling.
• Confirm that Settings > Permalinks does not use the Plain permalink structure.
• Confirm that the Work Directory under Staatic > Settings > Advanced exists or can be created, and is writable by PHP.

You can also run a publication from WP-CLI:

wp staatic publish

The WP-CLI Publish Command runs publication work from the command line and often avoids web request limits that affect WP-Admin publications.

Publication worker diagnostic

Staatic adds a Publication worker survival check to Tools > Site Health. It asks one Staatic background worker to stay alive for as long as the Publication Task Timeout allows, up to a maximum of five minutes, and reports whether the worker survived.

The check tells you whether background PHP work survives long enough to run publication tasks. It does not observe proxy or client responses, so it cannot prove that visitors avoid timeouts, and it does not measure whether the server has enough CPU capacity for the publication itself.

The diagnostic runs twice a day and can be started on demand from the action link in the Site Health result.

When the Publication Task Timeout is higher than five minutes, the result says which part of the runtime was verified: the diagnostic confirms its own five-minute cap, not the full configured runtime.

If a site has intentionally disabled the diagnostic, Staatic removes the Site Health check instead of reporting it as a problem.

Publication stalls or fails

Open the failed or stalled publication under Staatic > Publications and check the current task or last logged task.

WP-Admin publications run as background tasks. Some tasks can safely resume in a later request, including crawl and deployment work. If a task that cannot resume is reached a second time, Staatic marks the publication as failed and logs a message naming that task. The message points at the PHP error log for the actual cause, such as a fatal error, an out-of-memory condition, or a timeout, and suggests raising Publication Task Timeout when the log shows the task ran out of time.

Increasing Publication Task Timeout only helps when PHP and the web server allow requests to run long enough. If PHP-FPM, Nginx, Apache, LiteSpeed, a proxy, or a load balancer terminates requests earlier, raise those limits as well or use WP-CLI.

A publication is also canceled once it exceeds the Publication Time Limit, four hours by default. A publication that fails after roughly that long, on WP-Admin or on WP-CLI, has hit that limit rather than a task timeout.

Publication takes too long

Staatic crawls WordPress like a visitor. Large sites, slow origin responses, heavy plugins, limited hosting resources, and slow deployment targets can all increase publication time.

Practical tuning steps:

• Disable plugins that are not needed during publication, especially plugins that slow down frontend requests.
• Keep Logging at Minimal logging or No logging during normal operation.
• Tune HTTP Concurrency under Staatic > Settings > Advanced. Higher concurrency can speed up crawling on capable servers, but too much concurrency can overload PHP, the database, or the web server and cause 5xx responses.
• Check HTTP Delay. A non-zero delay intentionally slows the crawler.
• Increase HTTP Timeout only when origin requests legitimately need more time; do not use it to hide persistent slow responses.
• Use Staatic Premium partial publications when appropriate, but remember that partial publication is based on tracked changes, not a full backlink scan.
• For Local Directory deployments on Linux, consider Symlink/Copy Uploads to avoid crawling and copying every upload individually.
• For Staatic Cloud deployments with Staatic Premium, consider Uploads Sync so media is registered from the uploads directory instead of being crawled file by file.

If a publication is slow because WP-Admin background requests are constrained, use WP-CLI:

wp staatic publish --verbose

Staatic Cloud deployment issues

When using Staatic Cloud, a publication uploads a deployment manifest and required files before the deployment can be prepared and executed. A deployment can fail or remain unfinished when:

• the Staatic account connection or subscription is not valid;
• the site is not a Staatic Cloud site;
• a file upload is rejected because the uploaded data does not match the expected checksum;
• a file is too large for the deployment upload limit;
• a new publication supersedes an unfinished upload or prepared deployment;
• the final deployment to the static distribution fails.

Check the publication logs first. If the error points to Staatic Cloud and the local settings look correct, contact Staatic support with the publication ID, approximate time, and the relevant log excerpt.

Enable WordPress debug logging

Use WordPress debug logging when publication logs point to a PHP fatal error, theme error, plugin error, or blank response from the origin.

Add these lines to wp-config.php temporarily:

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

Start a new publication and wait until the failure happens. Then check:

wp-content/debug.log

Disable debug mode after troubleshooting. Debug logs can contain sensitive paths, tokens, request data, and plugin details.

Server limits to check

If publications fail around the same runtime, or the publication worker diagnostic reports that a worker did not survive its target runtime, check the request and process limits around WordPress.

As an operational baseline, a process open-file limit of at least 4096 is usually safer than the common default of 1024 for larger WordPress sites.