Fix Broken Links in WordPress

Learn how to update broken links on your Pantheon WordPress site so that the URL references the correct file path and domain name.

Discuss in our Forum Discuss in Slack

Whether by accident or by virtue of "web rot", links in your content may eventually stop working. This happens when links are placed into your site's code that use an IP address instead of your actual domain name. These links will eventually break when your application container’s IP address changes due to the nature of Pantheon’s cloud-based infrastructure.

Some code relies on $_SERVER['SERVER_NAME'] and $_SERVER['SERVER_PORT'] to construct URLs. This doesn't work well on Pantheon because this environmental data will be for ephemeral container data, which can lead to broken links. For more information, see SERVER_NAME and SERVER_PORT on Pantheon and WordPress Plugins and Themes with Known Issues.

There's a Plugin For That

As with most common problems WordPress site owners face, there's a plugin to help. Actually, there are many. If you go to and search for broken link, you'll find over 700 plugins to evaluate. The Broken Link Checker plugin is the most popular and is active on more than 400,000 WordPress sites.


You can install the plugin from your WordPress dashboard by following these steps:


Your site's Connection Mode must be set to SFTP.

  1. Click Plugins, then select Add New.
  2. Search for "Broken Link Checker".
  3. Click Install Now, then click Activate.

Using the Plugin

Once you have the plugin installed and activated, you will see a new option within the Tools section of your WordPress dashboard. Notice that there are no reported broken links. Don't get too excitedyou won't see any until WordPress runs it's next Cron job. In the background, WordPress will quietly check all your posts, comments, pages, etc., and look for broken URLs. Each URL is queued to be checked so that performance is not negatively affected. Check back later; if you have a lot of content, it will take a while to run.

Broken Link Checker won't keep you from creating bad links, it is simply a reporting tool. You can still do things that are a bad idea, like using the IP address for your site instead of its domain name, but this resource helps you clean things up. The best solution for linking to your own content is to use relative paths. Use /my-cool-blog-post instead of and you never have to worry about portability. For everything else, there is Broken Link Checker.

Update Environment URLs on Pantheon

WordPress stores URLs in various places in the database; considering Pantheon's multi-environment workflow, this can cause unexpected behavior. However, we've integrated the WP-CLI's search & replace functionality into the workflow to assist in updating these URLs. Dashboard DB URL converter Pantheon's workflow for WordPress includes an additional feature to update environment URLs automatically. Note that the defaults that are selected when performing a clone operation aren't overridable, as we update the URL to match whatever environment you're cloning to. We do offer the option to convert HTTP to HTTPS and vice versa; in the case you have HTTPS in one environment and not another.

Fix WordPress Content References to the Wrong Domain After Cloning

WordPress sites with custom domains configured on multiple environments may see references to the wrong platform domain after cloning the database from one environment to another.

The Site Dashboard runs wp search-replace during the cloning workflow to update environment URLs automatically. This operation, however, only runs once on a single set of URLs. If the target environment has a custom domain (e.g, it's used to replace the source environment's custom domain (e.g. This can cause the target environment to have incorrect references to platform domains (e.g.

You can resolve this using one of several methods:

There are several plugins with search and replace functionality. One reported by users to work well on our platform is WP Migrate DB. Make sure you select the Find & Replace functionality:

Enable Find & Replace

Another popular search-replace plugin is Better Search Replace but there is an additional filter that needs to be added for it to work on Live, as outlined in Plugins and Themes with Known Issues.

Using Terminus, you can run an additional wp search-replace command on the target environment after cloning. Set or replace the variables $site and $env with your site name and the correct environment:

terminus remote:wp $site.$env -- search-replace "://" "://" --all-tables --verbose --dry-run

The following example also converts the URL from HTTP to HTTPS, for situations where you might have HTTPS in one environment and not another:

terminus remote:wp $site.$env -- search-replace "" "" --all-tables --verbose --dry-run

Note: The example code above includes --dry-run, which executes the command but prevents permanent changes. Remove this flag once confident that the values are correct.

For those using Quicksilver scripts, consider the following example. On each passthru line, replace and with the domains you want to find and replace, respectively:

echo "Replacing previous environment urls with new environment urls... \n";

if ( ! empty( $_ENV['PANTHEON_ENVIRONMENT'] ) ) {
    case 'live':
      passthru('wp search-replace "://" "://" --all-tables ');
    case 'test':
      passthru('wp search-replace "://" "://" --all-tables ');
      passthru('wp search-replace "://" "://" --all-tables ');
      passthru('wp search-replace "://" "://" --all-tables ');

The example above replaces three URLs when cloning to the test environment with, and replaces that domain with the example custom domain when cloning to the live environment.

You can find this example and many others in the Quicksilver Examples repo.


In addition to the style above, URLs may be stored in an encoded format. If the example above fails to resolve all issues, search for patterns like and :\/\/