Skip to main content

Fix Broken Links in WordPress

Learn how to update broken links on your Pantheon WordPress site.


This section provides information on how to correct broken links so that the URL references the correct file path and domain name.

Links in your content may stop working by accident or due to web rot. This happens when links placed in your site's code 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 is for temporary container data, which can lead to broken links. Refer to SERVER_NAME and SERVER_PORT on Pantheon and WordPress Plugins and Themes with Known Issues for more information.

Available Plugins

There are a number of plugins that can help you correct and maintain your links. Visit WordPress.org and search for broken links for a comprehensive list of plugins. The Broken Link Checker plugin is the most popular and is active on more than 400,000 WordPress sites.

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

  1. Set your Connection Mode to SFTP.

  2. Click Plugins, then select Add New.

  3. Search for Broken Link Checker.

  4. Click Install Now, then click Activate.

Use the Plugin

You will see a new option within the Tools section of your WordPress dashboard when the Broken Link Checker plugin is installed and activated. Notice that there are no reported broken links. This is normal as broken links aren't identified until WordPress runs it's next Cron job. WordPress checks all your posts, comments, pages, etc., in the background and look for broken URLs. Each URL is queued to be checked so that performance is not negatively affected.

Broken Link Checker is a reporting tool and won't keep you from creating bad links. The best solution for linking to your own content is to use relative paths. Use /my-cool-blog-post instead of https://example.com/my-cool-blog-post to avoid portability problems.

Update Environment URLs on Pantheon

WordPress stores URLs in various places in the database. This can cause unexpected behavior due to Pantheon's multi-environment workflow. WP-CLI's search and replace functionality is integrated into the workflow to assist in updating URLs.

Dashboard DB URL converter

Pantheon's workflow for WordPress includes an additional feature to update environment URLs automatically. Note that you can't override the defaults that are selected when performing a clone operation when you update the URL to match whatever environment you're cloning to. You can convert HTTP to HTTPS and vice versa if this varies among your environments.

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 only runs once on a single set of URLs. If the target environment has a custom domain (e.g test.example.com), it's used to replace the source environment's custom domain (e.g. www.example.com). This can cause the target environment to have incorrect references to platform domains (e.g. live-example.pantheonsite.io).

You can resolve this using one of several methods:

There are several plugins with search and replace functionality. WP Migrate DB, for example, works well on our platform.

Make sure you select the Find & Replace functionality:

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

Info:
Note

In addition to the example above, URLs may be stored in an encoded format. If the example above fails to resolve all issues, search for patterns like %3A%2F%2Fexample.com and :\/\/example.com.

More Resources