AMP
VI
English Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski

AMP validation errors

Valid AMP documents must not include any validation errors. The purpose of this document is to help you better understand and fix any validation errors you encounter when you validate your AMP pages. For a complete overview of the validation errors, see the AMP validator specification.

AMP HTML tag and attribute errors

Mandatory tag missing

Code MANDATORY_TAG_MISSING
Format "The mandatory tag '%1' is missing or incorrect."
Fix Add (or correct) the mandatory HTML tag.

The following tags must be present in all AMP emails:

  • <!doctype html>
  • <html amp4email> or <html ⚡4email>
  • <head>
  • <meta charset="utf-8">
  • <style amp4email-boilerplate>body{visibility:hidden}</style>
  • <script async src="https://cdn.ampproject.org/v0.js"></script>
  • <body>

These mandatory tags include a mandatory: true field in the AMP validator spec; they are also referenced in the AMP specification.

Tag required by another tag is missing

Code TAG_REQUIRED_BY_MISSING
Format "The '%1' tag is missing or incorrect, but required by '%2'."
Fix Add (or correct) the required HTML tag.

The validator throws the TAG_REQUIRED_BY_MISSING error when it finds an extended component in the AMP document, but doesn't find its equivalent <script>.

Extended components must be explicitly included in the AMP document as custom elements. To fix these errors, navigate to the extended component's reference page, copy its required script, and paste it into the AMP document <head>.

Disallowed tag

Code DISALLOWED_TAG
Format "The tag '%1' is disallowed."
Fix Remove the disallowed tag.

Tags are allowlisted, so there is no definitive list of all disallowed tags; however, the AMP specification broadly defines the set of disallowed tags.

Custom JavaScript is not allowed

Code DISALLOWED_SCRIPT_TAG
Format "Custom JavaScript is not allowed."
Fix Remove the javascript tags or use amp-script.

The AMP format does not allow custom JavaScript to be added to pages via the <script> element. Many common uses of JavaScript have AMP HTML library equivalent implementations. See AMP components for the set of components that can be used to enhance AMP HTML pages.

If none of the available components cover your use case, amp-script can be used to run your custom JavaScript.

Mandatory attribute missing

Code MANDATORY_ATTR_MISSING
Format "The mandatory attribute '%1' is missing in tag '%2'."
Fix Add mandatory attribute to tag.

Mandatory attributes for AMP tags are defined within AMP's validator spec. Simply search for the tag, view the listed attributes, and check for mandatory: true. Mandatory attributes for each AMP tag are also listed within the tag's specification.

Invalid attribute value

Code INVALID_ATTR_VALUE
Format "The attribute '%1' in tag '%2' is set to the invalid value '%3'."
Fix Fix the attribute value to something that is valid.

This error indicates that an HTML tag has an attribute with an allowed name, but not an allowed value. For example, one common trigger for this error is invalid values for URLs. All URLs values (in href and src attributes) must match one of these possible attribute values.

IMPORTANT: Many URL values in AMP require HTTPS. If you are getting this error, and aren't sure why, check the relevant AMP tag's specification to see if the attribute requires HTTPS.

Disallowed attribute

Code DISALLOWED_ATTR
Format "The attribute '%1' may not appear in tag '%2'."
Fix Remove the attribute from the HTML tag.

Attributes are allowlisted, so there is no definitive list of all disallowed attributes. To check the supported attributes for each specific tag, search for HTML tag, and then attrs in the AMP validator spec.

In addition to a allowlist of specific attributes for each tag, all AMP tags can use any of the attributes allow-listed under $GLOBAL_ATTRS; all attributes with a prefix of "data-" are also allowlisted.

Mandatory text missing or incorrect

Code MANDATORY_CDATA_MISSING_OR_INCORRECT
Format "The mandatory text (CDATA) inside tag '%1' is missing or incorrect."
Fix Add or correct the mandatory text inside the tag.

CDATA is the content data between a start and end HTML tag and is currently evaluated with both allowlists and denylists. Tags with mandatory CDATA include:

<style amp-boilerplate>body{-webkit-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-moz-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-ms-animation:-amp-start 8s steps(1,end) 0s 1 normal both;animation:-amp-start 8s steps(1,end) 0s 1 normal both}@-webkit-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-moz-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-ms-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-o-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}</style><noscript><style amp-boilerplate>body{-webkit-animation:none;-moz-animation:none;-ms-animation:none;animation:none}</style></noscript>

And:

<style amp-custom>

Detailed messages for this can be one of the following:

  • "Mandatory style boilerplate (js enabled)"
  • "Mandatory style boilerplate (noscript)"
  • "Disallowed -amp- CSS class name prefix"
  • "Disallowed !important attribute in CSS"
  • "Disallowed @charset in CSS"
  • "Disallowed @import in CSS"
  • "Disallowed @namespace in CSS"
  • "Disallowed @supports in CSS"
  • "Disallowed @document in CSS"

  • "Disallowed @page in CSS"

    Disallowed text inside tag

    Code CDATA_VIOLATES_DENYLIST
    Format "The text (CDATA) inside tag '%1' matches '%2', which is disallowed."
    Fix Remove disallowed text.

    Specific CSS data has been denylisted to validate essential CSS AMP rules.

    The following is the list of denylisted CSS data (see also disallowed_cdata_regex in the AMP validator spec):

    • "\\.i?-amp-" ("CSS -amp- class name prefix")
    • "!important"
    • "charset"
    • "&#64;import"
    • "@namespace"
    • "@document"

    • "@page"

      Invalid property value

      Code INVALID_PROPERTY_VALUE_IN_ATTR_VALUE
      Format "The property '%1' in attribute '%2' in tag '%3' is set to '%4', which is invalid."
      Fix Correct the invalid property value.

      This error occurs when the property value inside an attribute is invalid. The term property in this context means the structured key/value data inside an attribute.

      Missing URL

      Code MISSING_URL
      Format "Missing URL for attribute '%1' in tag '%2'."
      Fix Add the valid URL.

      This error occurs when an attribute that requires a URL is missing it, for example, an empty href or src attribute.

      Invalid URL

      Code INVALID_URL_PROTOCOL
      Format "Malformed URL '%3' for attribute '%1' in tag '%2'"
      Fix Fix the broken URL.

      This error occurs when a attribute has a URL, but the URL is invalid.

      Invalid URL protocol

      Code INVALID_URL_PROTOCOL
      Format Invalid URL protocol '%3:' for attribute '%1' in tag '%2'.
      Fix Change to a valid protocol, for example, `http` may need to be `https`.

      This error occurs for tags that have an href or src that must be set to certain protocols. For example, many tags require https.

      Mutually exclusive attributes

      Code MUTUALLY_EXCLUSIVE_ATTRS
      Format "Mutually exclusive attributes encountered in tag '%1' - pick one of %2."
      Fix Remove one of the mutually exclusive attributes.

      This error occurs when a tag has both of the mutually exclusive attributes. For example, only one is allowed for the following tags:

      Missing mandatory attribute from list

      Code MANDATORY_ONEOF_ATTR_MISSING
      Format "The tag '%1' is missing a mandatory attribute - pick one of %2."
      Fix Add the missing mandatory attribute from the choice of attributes provided.

      This error occurs when a tag is missing one required attribute from multiple choices. For example, these tags require one attribute from two possible choices:

      Wrong parent tag

      Code WRONG_PARENT_TAG
      Format "The parent tag of tag '%1' is '%2', but it can only be '%3'."
      Fix Make the tag a direct child of the required parent.

      Specific tags require an immediate parent (as opposed to distant ancestor). The following lists the required parent for specific tags (tag, parent):

      • !doctype requires parent tag root.
      • html requires parent tag !doctype.
      • head requires parent tag html.
      • body requires parent tag html.
      • link requires parent tag head.
      • meta requires parent tag head.
      • style amp-custom requires parent tag head.
      • style requires parent tag boilerplate (noscript).
      • noscript requires parent tag head.
      • script requires parent tag head.
      • source requires a media tag (amp-audio, amp-video, etc.).

      Disallowed tag ancestor

      Code DISALLOWED_TAG_ANCESTOR
      Format "The tag '%1' may not appear as a descendant of tag '%2'."
      Fix Remove (or move) the disallowed nested tag.

      This error occurs when a tag is a descendant of another tag which doesn't validate. Currently, the only example is a template tag, which may not be nested under another template tag.

      Mandatory tag ancestor

      Code MANDATORY_TAG_ANCESTOR
      Format "The tag '%1' may only appear as a descendant of tag '%2'."
      Fix Either remove the tag or make it a descendant of the specific tag.

      Mandatory descendants are defined in the AMP validator specification as mandatory_ancestor.

      The error occurs when the following tags are missing their mandatory_ancestor (tag, ancestor):

      • img must be a descendant of noscript.
      • video must be a descendant of noscript.
      • audio must be a descendant of noscript.
      • noscript must be a descendant of body.

      Duplicate unique tag

      Code DUPLICATE_UNIQUE_TAG
      Format "The tag '%1' appears more than once in the document."
      Fix Remove one of the duplicate tags from the AMP document.

      This error occurs when exactly one instance of the tag is allowed, and a duplicate is found.

      The full list of unique tags is known:

      • <doctype html>
      • <html amp>
      • <head>
      • <link rel=canonical href=...>
      • <link rel=amphtml href=...>

      • <meta charset="utf-8"> * <style amp-custom> * <style amp-boilerplate>body{-webkit-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-moz-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-ms-animation:-amp-start 8s steps(1,end) 0s 1 normal both;animation:-amp-start 8s steps(1,end) 0s 1 normal both}@-webkit-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-moz-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-ms-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-o-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}</style><noscript><style amp-boilerplate>body{-webkit-animation:none;-moz-animation:none;-ms-animation:none;animation:none}</style></noscript> * <body> * <script src="https://cdn.ampproject.org/v0.js">

        Style and layout errors

        Before diving into style and layout errors, it's worth understanding how styling and layout work in AMP. Since AMP pages are HTML pages, styling is very much the same as any HTML page. But there are some restrictions to ensure pages load fast, and the AMP validator enforces these restrictions.

        Layout is more controlled in AMP pages. Any tag that gets displayed on the page requires a pre-defined height and width, significantly reducing rendering and scrolling jank. This doesn't mean that you have to manually include these attributes. For certain layout types, the AMP validator won't throw errors as default values are assumed.

        Each AMP tag has a ist of supported_layouts, as defined in the AMP validator specification. The validator will throw errors for unsupported layouts, and it will check validation rules for the pre-defined layout.

        Stylesheet too long

        Code STYLESHEET_TOO_LONG
        Format "The author stylesheet specified in tag 'style' is too long - we saw %1 bytes whereas the limit is %2 bytes."
        Fix Reduce the size of the stylesheet to be under 75,000 bytes.

        The AMP validator throws this error when it measures the size of the styles content within <style amp-custom> to exceed the 75,000 bytes limit.

        CSS syntax error

        Code CSS_SYNTAX
        Format "CSS syntax error in tag '%1' - %2."
        Fix Fix the CSS syntax error.

        This error occurs when you've CSS syntax errors in the specified tag. If you aren't sure what's causing the error, try running the CSS through an online CSS validator, for example, csslint.

        CSS syntax error at specific rule

        Code CSS_SYNTAX_INVALID_AT_RULE
        Format "CSS syntax error in tag '%1' - saw invalid at rule '%2'."
        Fix Fix the specified CSS syntax error.

        This error refers to the @-rules within CSS, for which AMP only allows a handful of rules. (see also the AMP specification). For example, @import isn't allowed. The validation error specifically tells you the rule that's invalid, making it easier to fix that rule.

        Implied layout isn't supported by AMP tag

        Code IMPLIED_LAYOUT_INVALID
        Format "The implied layout '%1' is not supported by tag '%2'."
        Fix Provide a valid layout attribute for the tag.

        This error occurs when you don't specify a layout for the AMP tag, and the implied layout (based on width, height, and sizes) isn't supported. Check the supported_layout values for the tag in the AMP validator specification.

        Actual layout behavior is determined by the layout attribute. For more on how layout works, see How to Control Layout and the AMP HTML layout system specification.

        NOTE – If you don't specify the layout, and you don't include width and height values, the layout defaults to CONTAINER. The validator throws an error as CONTAINER isn't supported in any AMP tags. Specify a layout other than CONTAINER, or add a width and/or height value and the error goes away.

        Attribute not allowed by implied layout

        Code ATTR_DISALLOWED_BY_IMPLIED_LAYOUT
        Format "The attribute '%1' in tag '%2' is disallowed by implied layout '%3'."
        Fix Remove the disallowed attribute from the tag, or else specify a layout that allows it.

        This error occurs when you don't specify a layout for the AMP tag, and the implied layout contains a disallowed attribute. Disallowed attributes for layout types are described in the AMP HTML layout system specification.

        Specified layout isn't supported by AMP tag

        Code SPECIFIED_LAYOUT_INVALID
        Format "The specified layout '%1' is not supported by tag '%2'."
        Fix Specify a layout that is supported by the tag.

        This error occurs when the specified layout for the tag isn't supported. Check the supported_layout values for the tag in the AMP validator specification.

        Actual layout behavior is determined by the layout attribute. For more on how layout works, see How to Control Layout and the AMP HTML layout system specification.

        Attribute not allowed by specified layout

        Code ATTR_DISALLOWED_BY_SPECIFIED_LAYOUT
        Format "The attribute '%1' in tag '%2' is disallowed by implied layout '%3'."
        Fix Remove the disallowed attribute from the tag, or else specify a layout that allows it.

        This error occurs when you specify a layout for the AMP tag, and the layout contains a disallowed attribute. Disallowed attributes for layout types are described in the AMP HTML layout system specification.

        Invalid value for attribute required by layout

        Code ATTR_VALUE_REQUIRED_BY_LAYOUT
        Format "Invalid value '%1' for attribute '%2' in tag '%3' - for layout '%4', set the attribute '%2' to value '%5'."
        Fix Set the attribute to the specified value.

        This error occurs when the attribute value is invalid for the specified layout. To understand what triggers this error, you need to familiarize yourself with the different behaviors of layouts.

        Let's say you set the layout to be fixed-height and you include numeric values for both height and width. The fixed-height layout takes on a height value. The width attribute must not be present or else set to auto. The validator throws the ATTR_VALUE_REQUIRED_BY_LAYOUT.

        Inconsistent units for width and height

        Code INCONSISTENT_UNITS_FOR_WIDTH_AND_HEIGHT
        Format "Inconsistent units for width and height in tag '%1' - width is specified in '%2' whereas height is specified in '%3'."
        Fix Provide consistent unit widths and heights.

        With the exception of layout=fixed, width and height attributes need to be expressed in the same units. When they are not, this error is triggered.

        For example, <amp-img src="" layout="responsive" width="42px" height="42rem">, results in this error message:

        "Inconsistent units for width and height in tag 'amp-img - width is specified in 'px' whereas height is specified in 'rem'."

        Templating errors

        AMP pages can't include templating syntax, unless that syntax is within an AMP tag specifically designed to include templates, for example, amp-mustache.

        It's OK to include templates in your source files, so long as the generated output of those files doesn't contain the templates (see also Use CSS preprocessors).

        Attribute contains template syntax

        Code TEMPLATE_IN_ATTR_NAME
        Format "Mustache template syntax in attribute name '%1' in tag '%2'."
        Fix Remove Mustache template syntax from the attribute.

        This error occurs anytime the validator finds Mustache template syntax in an attribute value.

        Attribute contains unescaped template syntax

        Code UNESCAPED_TEMPLATE_IN_ATTR_VALUE
        Format "The attribute '%1' in tag '%2' is set to '%3', which contains unescaped Mustache template syntax."
        Fix Escape the mustache template.

        This error occurs anytime the validator finds unescaped Mustache template syntax in an attribute value.

        Attribute contains template partial

        Code TEMPLATE_PARTIAL_IN_ATTR_VALUE
        Format "The attribute '%1' in tag '%2' is set to '%3', which contains a Mustache template partial."
        Fix Remove the mustache partial.

        This error occurs anytime the validator finds a Mustache partial in an attribute value.

        Deprecation errors

        Deprecated tag

        Code DEPRECATED_TAG
        Format No error message defined as yet (no deprecated tags).
        Fix Remove the deprecated tag.

        This warning occurs when a previously valid AMP tag is found in the AMP document. It's only a warning; AMP documents with warnings continue to be valid. Currently no deprecated tags exist; the warning is reserved for future deprecations.

        Deprecated attribute

        Code DEPRECATED_ATTR
        Format "The attribute '%1' in tag '%2' is deprecated - use '%3' instead."
        Fix As good practice, remove the deprecated attribute.

        This warning occurs when a previously valid AMP attribute is found in the AMP document. It's only a warning; AMP documents with warnings continue to be valid.

        Identify deprecated attributes for each AMP tag by searching for deprecation in the AMP validator specification.