Home / Documentation / Setting up Staatic / Troubleshooting

Troubleshooting

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

Location What to check
Tools > Site Health Staatic checks for permalink structure, writable work directory, publication task runtime, and loopback requests. Also check WordPress scheduled events, HTTP requests, and loopback requests.
Staatic > Publications Confirm whether a publication is pending, in progress, failed, canceled, or finished. The current task helps identify where it stopped.
Publication Details Review the publication summary and log entries. Increase logging temporarily if the logs are too sparse.
Publication Resources Inspect crawled resources by status. HTTP 4xx and 5xx responses usually point to origin, plugin, theme, authentication, or server issues.
Staatic > Settings > Advanced Check work directory, logging, publication task timeout, HTTP timeout, HTTP concurrency, HTTP authentication, SSL certificates, and custom origin URL.

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 task and loopback warnings.
  • If Site Health says the publication test task has not started, verify that WP-Cron and background requests can run.
  • 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 stalls or fails

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

Task area Common cause What to check
Setting up Work directory or deployment configuration problem. Confirm the work directory is writable and the selected deployment method validates successfully.
Initializing crawler No crawl URLs can be enqueued. Check permalink structure, destination URL, custom origin URL, and whether the origin is reachable from the server.
Crawling Origin requests fail or return unexpected responses. Inspect Publication Resources for 4xx/5xx responses and check HTTP authentication, SSL verification, blocked server IPs, plugin errors, and theme errors.
Post-processing A plugin, theme, or custom integration fails while generated resources are being processed. Review publication logs and temporarily enable WordPress debug logging.
Initializing deployment Deployment method is missing or invalid. Re-test the deployment method settings and credentials.
Deploying Upload, file, or remote service failure. Check deployment credentials, destination permissions, remote service status, and publication logs.
Indexing Premium Search indexing issue. Check Staatic account connection and publication logs. Indexing can add time and may log warnings for individual indexing operations.

WP-Admin publications run as background tasks. Some tasks can safely resume in a later request, including crawl and deployment work. If a non-restartable task times out or hits a fatal error, Staatic marks the publication as failed and logs a message recommending the Publication Task Timeout setting.

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.

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.

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 Site Health publication test reports a low timeout, check the request and process limits around WordPress.

Component Common setting Why it matters
PHP max_execution_time Limits how long PHP scripts may run.
PHP-FPM request_terminate_timeout Can terminate PHP requests even when WordPress asks for more time.
Nginx proxy_read_timeout, proxy_connect_timeout, proxy_send_timeout, send_timeout Can terminate long-running admin or crawler requests.
Apache TimeOut Can terminate long-running requests.
LiteSpeed noabort, noconntimeout Controls whether PHP continues after the client connection ends.
Linux/macOS open file limit Very low limits can cause file, class-loading, or network errors under load.

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.