Troubleshooting failed static site generation

WP Static Site Generators
#1

This should help in general with any WordPress Static Site Generators. Work through the list for ways to check/debug the issue you’re having.

Troubleshooting a failed export

  • Browser
    • disable browser extensions
    • try in a new incognito/private session
    • anything in the browser’s console?
      • JavaScript errors
      • Open Network tab when exporting (slower) and inspect the last XHR request before export failed (ignoring WP “heartbeats”
  • Is your site authenticated?
    • use Basic Auth setting
  • PHP Version
    • Update to 7.4+
  • Server environment
    • windows IIS not supported (use Local by FlyWheel, AMPPS, WSL, etc)
    • disable mod security
    • disable mod pagespeed (does weird things to URLs)
    • PHP max_execution_time - set this as high as you can
    • PHP memory_limit - set this as high as you can
    • cURL and zip extensions enabled for PHP
    • CloudFlare or other security at the DNS layer, try disabling
  • WordPress environment
    • Permalinks need to be set (no index.php or query strings in your URLs)
  • Conflicting plugins
    • disable all but the static site generator plugin you are using
  • Missing images, styles, etc
    • switch to the default TwentySeventeen theme, if that doesn’t export properly, the problem is more than just your theme
    • open browser console to Network tab, reload exported site and check for any 404’s
    • open browser console to Console tab, reload exported site and check for any 404’s, JS errors or mixed-content errors preventing things loading
    • add any missing URLs to the Additional URLs field to force them to be crawled
  • Compare the source code in your development WP site to your exported site
    • validate your development site’s source code
1 Like
#2

An issue I had on my end was with a Docker container. I had mapped port 80 in the container to port 8080 on the Docker host. In the Wordpress settings, the site url was set to localhost:8080, but when the plugin tried to access localhost:8080 from inside the container, it understandably didn’t work.

The solution for me was first logging in to the Wordpress admin console in the container and changing the WordPress Address (URL) and Site Address (URL) from http://localhost:8080 to http://localhost, then pressing save (which will appear to take the site offline). Then I stopped the container and relaunched it with the port mapping changed, from 8080:80 to just 80:80. At that point the plugin worked as expected.

If changing ports is not an option, I suppose another solution could be some way of running the plugin through the CLI in another container than the container running Wordpress, and in a different network context, or running the plugin on the host, but I didn’t get those other options working.

1 Like
#3

Thanks for reporting, @jscushman!

I have another side project which spins up containers and maps the host/guest ports to remove the headaches with this situation. It’s advancing a bit from the image used in the publicly available script here, but the aim is to not require any config on the host at all, so I’m looking to remove the localhost subdomains completely and use the script’s UI to keep manage multiple sites by a friendly name (but each site will just be localhost with a different port): https://lokl.dev

That’s aiming to be simple as possible for beginners, but for anyone who really wants nice domains, complex setups, that may be possible to support via some extra fields in the plugin to overide the site url and crawl urls used when crawling/rewriting