AMP Plugin Troubleshooting Guide

If you encounter any unusual behavior on your AMP URLs you can use this guide to help you determine the potential causes. Unusual behavior refers to anything not working in your AMP URLs as it does in your non-AMP URLs, and not specifically AMP validation errors.

Using the Plugin’s Developer Tools #

The plugin has useful built-in developer tools to help determine the source of issues you may be encountering. See our documentation on how the plugin handles such validation errors for further insights. In many cases, a third-party plugin may be outputting custom JavaScript on the front end of your site, without any no-JS fallback which the plugin would use for the AMP version by default. In other words, if your theme appears broken on the non-AMP version with JS turned off in the browser, it’s very likely that the AMP version will be broken with JS turned on. 

To perform such a check there are a few methods to do so. As you’ve probably landed on this troubleshooting guide from noticing some unusual behavior by visiting an AMP URL we’re going to use the admin toolbar to try and determine the source. Please follow the steps below:

1. Ensure you have your WordPress admin toolbar enabled, while also ensuring the “AMP Developer Tools” option is also enabled (“Users > Profile” from within your WordPress administrator dashboard).

2. Visit that AMP URL once more, where you’re encountering any issues. 
3. Hover over the “AMP” toolbar tab. You’ll find a “Validate URL” option 
4. Click on that link and you’ll be directed back to your admin panel, with additional insights on this validation error. 

5. This AMP validator page can help you pinpoint any third-party plugin, markup, or other source of issues you may be encountering on this URL. 
6. If you’re able to determine the source of the issue using the validation tool see the option below “What to do when you determine the source of issues on your AMP URLs?”
7. If you’re unable to determine the source of the issue, if you need assistance or if no validation errors occur feel free to open a support topic.  

Additional Insights using the validation tool: #

If you want to dig deeper and understand the validation errors across your site and not specific to one URL you can use the plugin’s developer tools, which comprises the below tabs:

• Validated URLs: This lists all URLs on your site that have been analyzed by the AMP plugin. It also lists the AMP status of that page, the number of AMP validation errors, the source, CSS usage of that URL, and the timestamp of the last validation check. 
• Error Index:  This lists all AMP validation errors on your site, along with the current status, type, additional context, and occurrences. 

The tool is great for navigation through validation errors, while also allowing users to choose a course of action when AMP validation errors are found. By default, the AMP plugin removes any invalid markup to ensure an AMP valid page, while also allowing users to keep this functionality if they wish. Just note that “keeping” such AMP invalid markup will result in any URLs with such validation errors not being valid AMP, and on a paired AMP site the user will be redirected to the non-AMP version whereas on an AMP-first site an unmarked AMP page will be served. 

Using the Health Check & Troubleshooting Plugin #

Using the Health Check & Troubleshooting plugin can be a great way to help determine the source of issues on your AMP URLs. The plugin features a “Troubleshooting” mode, which, once enabled, deactivates all plugins and switches to a core WordPress theme without impacting non-administrators. 

To use it follow the steps below:

1. Login to your WordPress administrator panel
2. Ensure you have your WordPress admin toolbar enabled (“Users > Profile > Toolbar”). If not enable it.
3. Install and activate the Health Check and Troubleshooting plugin
4. On the “Plugins” screen that appears click on the “Troubleshooting” link next to the AMP plugin. 
5. Open an AMP URL where you were encountering unusual behavior or issues. 
6. If the issue remains this may be related to the content of that particular URL. Review the content or open a support topic in the WordPress support forums. 
7. If the issue no longer appears this is an indicator that a theme or third-party plugin is resulting in this issue. To troubleshoot hover over the “Troubleshooting Mode” icon and enable your active plugins, one by one. Each time you activate a plugin while in troubleshooting mode the page will reload. Check for the same issue each time. 
8. If you’re unable to locate the source of the issue after having re-enabled all plugins switch to the theme you normally have active. 
9. If the issue appears once you’ve switched themes while in troubleshooting mode this is an indicator that there is some aspect of your theme causing this issue. Feel free to share your findings via opening a WordPress support topic and we’d be happy to assist. 

Spot the culprit? 

What to do when you determine the source of issues on your AMP URLs? #

There are certain avenues you can take once you determine something doesn’t work in your AMP URLs as it does in your canonical (non-AMP) URLs. We will suggest approaching them in following sequence:

1. Reach out to your theme or plugin developer: In many cases, plugin or theme authors can address any incompatibility issues you may be encountering. Reach out through the respective channels. 
2. Looking for AMP compatible alternatives: If you’re using a plugin that is not fully AMP valid why not look for AMP valid alternatives. In many cases, contact forms, block builders, or themes can be replaced with similar AMP comptible alternativesa. 
3. Use the Plugin Suppression feature: Uses can “suppress” the plugin from rendering on AMP URLs to ensure full AMP compatibility. An example of where this is particularly in with optimization plugins that have lazy loading features Lazy loading is already built into every AMP URL. 
4. Open a WordPress support topic: We’re always happy to help as much as we can within the support forums. Before opening a WordPress support forum topic please read our FAQs, which cover many topics which may answer your question or query. 
5. Making your own programmatic changes: If you have the technical expertise you can make your own changes to ensure full AMP compatibility. Making use of AMP components such as amp-bind or amp-script can ensure JavaScript functions such as toggling states can work in AMP URLs. You’ll find additional hamburger menu documentation by visiting this resource.  
6. Seek Professional Help (AMP Expert): in case you are tech-savvy and need professional help, we will recommend getting help from AMP experts listed on our site.
7. File a GitHub issue: If you can determine a bug or issue that needs to be addressed on the plugin side you can file an issue. Alternatively, if you feel there is something that can be improved submit a feature request. 

If reaching out to us in the WordPress support forums or on our GitHub repository note that we’re unable to make programmatic changes to third-party plugins. Should you determine issues related to such third-party plugins or themes your best course of action would be to check with the developers and enquire about AMP support.