This page is a collection of common troubleshooting tactics, curated from our Customer Success Engineers and the Pantheon community. These procedures can help you solve issues your site may have, or rule out potential causes.
Like all Pantheon docs pages, this is a living document. Please feel free to add your expertise to the page to help others.
These sections cover basic principles of troubleshooting, and apply to most issues.
If you're fielding a bug report from an end-user, it's helpful to reproduce the issue yourself in order to find the cause. For example, if a user reports they’re unable to sign up for an account, try signing up for an account yourself using the same steps to understand exactly what occurs.
Live sites do not show errors by default, but you can spot them by reviewing the PHP error log, or in Drupal, checking the watchdog log if the core dblog module is enabled.
In some cases, you may also run into the notorious “White screen of death” (WSOD), in which nothing prints to the screen at all. Similarly, in Drupal, you may see the cryptic “This website has encountered an unexpected error” message. If this happens, check the logs.
If you’re not sure if what you see in the log is coming from the problem at hand, try to reproduce the problem, then check your logs again.
If you’re handling a report of a problem from someone else and can’t reproduce it yourself, ask them what time the problem occurred so that you can compare that report to timestamps in the error log. Keep in mind that you may have to convert timezones depending on where your users are.
PHP errors coming from Drupal or WordPress code tend to not be specific to Pantheon, so a good first step on these if you’re not clear what the error means is to just search for it in your favorite search engine.
To learn more about PHP errors, see our PHP Errors and Exceptions documentation.
If you’ve narrowed the problem down to a specific module or plugin and you’re running an outdated version, try updating it first. The new release may include a fix for the issue, but even if it doesn’t, you’ll need to be running the newest version to report an issue.
Sometimes your CMS may encounter issues due to cached data that ends up in an odd state.
- Clear your site cache using the Pantheon Dashboard, or with Terminus.
- Clear all keys from the Object Cache using the Redis CLI.
- Review the caching logic for your CMS version. Drupal 9, for example, has some specific caching features that may be a factor.
- For issues confined to a specific page or display element, review the specific caching logic for your site or page.
- If the Pantheon Advanced Page Cache plugin or module is installed to take advantage of the granular cache clearing capabilities of the Global CDN, review these settings as well.
- Certain Drupal modules and WordPress plugins can conflict with Pantheon's granular cache clearing and header system. Review the Modules and Plugins With Known Issues pages to identify potential conflicts.
Site problems may feel random, but they’re all triggered by something. Was there a recent code change? A plugin update? A configuration edit? Rolling things back can be a good first step to troubleshoot, even if it seems unlikely to be related.
We recommend rolling back either the code or database versus a full restore in most cases. You can do this using Terminus.
If there haven’t been any code or config changes lately, an uptick in site traffic or the type of traffic you’re serving (e.g, uncached versus cached) may be the trigger. To see if this is the case, check your nginx access logs.
Some issues don’t give you clear errors or a trace back to the exact place things go wrong. In that case, you may want to try the “process of elimination” style of debugging on your Dev or multidev environment:
- Disable modules/plugins one by one
- Switch the theme to a Twenty* (WordPress) or Bartik (Drupal)
Continue doing this until the problem no longer comes up.
More complex issues with code may necessitate using debugging tools beyond your server or application logs.
- Recreate the issue locally.
- For WordPress, enable WP_DEBUG & WP_DEBUG_LOG in wp-config.php. Then use the debug.log file to find warnings and errors.
- Use Xdebug with a local development tool like Lando to set application breakpoints and dig into stack traces. See Lando documentation for more on working with their Xdebug settings.
In general, if the Pantheon Dashboard stops responding, the first step is to refresh the page. The next step is to log out and back in to the Site Dashboard. If the problem persists, contact support.
When resolving issues with Pantheon's HTTPS certificates, a good first step is to remove and re-add the domain, which will restart the certificate provisioning process.
If changes to your code don't appear to be showing:
Check that there isn't a
.gitignorethat may be ignoring those files:
git check-ignore -v path/to/file)
Check Composer dependencies as well. When a Composer package has a
.gitignore or a
.git/ folder in it, the platform is going to ignore the files in that folder.
See Apply Upstream Updates Manually from the Command Line to Resolve Merge Conflicts on our WordPress and Drupal Core Updates page for more information on core update conflicts. Note, deleted
README.txt files can cause dashboard conflicts.
For conflicts introduced by other code merges (like from Multidev environments), see Resolve Git Merge Conflicts.
The WSOD is a frustrating issue on WordPress and Drupal sites, since it provides no useful information on the cause. The first place you should look for information is the log files. See PHP Errors and Exceptions for more information on the type of errors you may find.
If your WordPress site exhibits unwanted behavior and you're not sure of the cause, try disabling all your plugins, or disable plugins incrementally. If the behavior stops, turn the plugins back on one by one, checking after each one to identify the culprit.
Some themes can cause potential conflicts with WordPress core, especially after core or plugin updates. To rule out the issue being your theme, switch to a default theme such as Twenty Nineteen.
There are times the permalink structure in WordPress is not updated properly, leading to 404 errors. Go to Settings > Permalinks in your WordPress Dashboard and click Save Changes.
Check that the WordPress Address and Site Address are properly configured in your WordPress Dashboard. These can also be overwritten in your
define('WP_HOME', 'https://example.com'); define('WP_SITEURL', 'https://example.com');
You must enable cookies for WordPress users to log in to their admin interface. You may need to add this to your
define('COOKIE_DOMAIN', $_SERVER['HTTP_HOST'] );
Are you a Drupal 7 wizard? Help us expand this section.
$config['system.logging']['error_level'] = 'verbose';