Back to Community
Home / Community / Plugin → Amp

Troubleshooting Common AMP Validation Errors: A Comprehensive Guide

23 threads Sep 17, 2025 Plugin → Amp

Content

If you've recently found a flood of AMP validation errors in Google Search Console, you're not alone. A sudden appearance of issues like The parent tag of the 'html' tag must be '!doctype', A mandatory AMP HTML tag is missing, or Custom JavaScript is not allowed is a common experience for many WordPress site owners. This guide will help you understand why these errors occur and walk you through the most effective steps to resolve them.

Why Do These AMP Validation Errors Happen?

These errors typically surface after an update to one of the core components of your website. This could be an update to:

  • The WordPress AMP plugin itself.
  • Your WordPress theme (e.g., Newspaper, ChromeNews, tagDiv).
  • Another plugin that modifies your site's HTML, CSS, or JavaScript output (e.g., caching plugins like W3 Total Cache, page builders, or optimization tools).
  • WordPress core (e.g., the introduction of the fetchpriority attribute in WordPress 6.3).

These updates can sometimes inject code, attributes, or structural changes that do not comply with the strict AMP HTML specification, causing previously valid pages to break.

Most Common AMP Errors and How to Fix Them

1. Structural and DOCTYPE Errors

Errors include: "The parent tag of tag 'html' must be '!doctype'", "A mandatory AMP HTML tag is missing", "Tag found outside the document head".

Why it happens: These are fundamental structural errors. The AMP specification requires a precise document structure, including a correct DOCTYPE and specific tags in the <head> section. A theme or plugin update may have corrupted this structure.

How to fix it:

  1. Test with the AMP Validator: Use the official AMP Validator or Google's AMP Test tool to confirm the errors on a specific URL.
  2. Conflict Test: The most reliable method is to perform a conflict test. Temporarily switch your theme to a default WordPress theme like Twenty Twenty-Four and disable all plugins except the AMP plugin. If the errors disappear, reactivate your theme and plugins one-by-one, checking the validator after each, to identify the culprit.
  3. Check Theme Compatibility: Many popular themes, such as Newspaper by tagDiv, offer dedicated AMP-compatibility plugins or require specific settings. Check your theme's documentation for AMP-specific instructions.

2. CSS and Style Tag Errors

Errors include: "The 'style amp-custom' tag appears multiple times", "Only amp-boilerplate and amp-custom 'style' tags are allowed".

Why it happens: AMP only allows one <style amp-custom> tag in the <head>. A plugin or theme might be incorrectly adding additional inline CSS or stylesheets.

How to fix it: Follow the conflict test above. The offending plugin or theme will need to be configured to stop outputting extra CSS on AMP pages. Caching plugins can sometimes incorrectly combine styles; check their settings for CSS optimization options that might need adjustment.

3. Disallowed Attributes and Tags

Errors include: "Disallowed attribute or attribute value present in HTML tag", "Invalid Element: ahref", "The attribute 'fetchpriority' may not appear in tag 'amp-img'".

Why it happens: AMP has a very limited set of allowed attributes for HTML tags. Common offenders include loading="lazy", decoding="async", fetchpriority="high", or custom data-* attributes added by other plugins or themes.

How to fix it:

  1. Identify the specific attribute causing the issue using the validation tool.
  2. The AMP plugin's sanitizer will often remove these attributes automatically. If the resulting page is acceptable, you may not need to do anything else.
  3. If the attribute breaks functionality (e.g., an image doesn't load), you will need to track down the source of the attribute using the conflict test method and either configure that software to not output it on AMP pages or find a suitable alternative.

4. Script and AMP Component Errors

Errors include: "Custom JavaScript is not allowed", "The tag 'amp-instagram v0.1 module extension script' is present, but is excluded by the presence of the tag 'amp-instagram 1.0'".

Why it happens: AMP pages cannot contain custom JavaScript. Furthermore, using multiple, conflicting versions of an AMP component script (like amp-instagram) will cause validation failures.

How to fix it: For custom JavaScript, you must find and disable the plugin or theme feature that is injecting the script. For AMP component version conflicts, this is often caused by a theme or plugin embedding its own outdated version of a component. Ensure all your software is updated to their latest versions.

5. Web Stories Errors

Errors include: "Tag 'amp-story' is not allowed to have any sibling tags".

Important Note: The 'AMP' plugin for WordPress is separate from the 'Web Stories' plugin. The 'amp-story' tag is used for creating Web Stories.

How to fix it: For issues specifically with Web Stories, it is recommended to seek support from the dedicated Web Stories plugin support forum, as the problem lies within that specific plugin's output.

General Troubleshooting Workflow

  1. Validate: Always use the AMP Validator to get the exact error and the URL where it occurs.
  2. Conflict Test: Disable all plugins and switch to a default theme. If the error is gone, reactivate your components one-by-one to find the conflict.
  3. Check for Updates: Ensure your AMP plugin, theme, and all other plugins are updated to their latest versions.
  4. Consult Specific Support: If the error is traced to your theme or a specific plugin (e.g., W3 Total Cache, tagDiv Newspaper), consult that product's dedicated support channels for AMP-specific guidance.

By methodically working through these steps, you can identify the source of most AMP validation errors and restore your pages to a valid state. Remember, the conflict test is your most powerful tool in this process.

Related Support Threads Support