Common AMP Issues, Causes, and Solutions

Created by Harmeet Singh, Modified on Fri, 14 Feb at 1:17 PM by Harmeet Singh

AMP (Accelerated Mobile Pages) is a framework that enforces strict guidelines to ensure high-speed performance and smooth rendering of web pages. However, certain issues commonly occur due to violations of AMP’s rules. This document outlines common AMP errors, their

causes, and solutions, along with best practices to prevent them.

1. Missing URL in HTML tag <img>

Cause:

The <img> tag lacks a src attribute or contains an empty value.
The src URL is dynamically inserted via JavaScript, which is not allowed in AMP.

Solution:

Ensure every <img> tag has a valid src attribute.
Use <amp-img> instead of <img>:
Tag sample:
<amp-img src="https://example.com/image.jpg" width="600" height="400"
layout="responsive"></amp-img>

Prevention:

Always specify a valid src in <amp-img>.
Validate the page using AMP Validator.

2. Custom JavaScript is Not Allowed

Cause:

AMP does not support traditional JavaScript (<script> tags) for security and performance reasons.

Solution:

Use AMP components instead, such as:
<amp-carousel> for sliders
<amp-bind> for interactivity
<amp-analytics> for tracking.

Prevention:

Replace standard JavaScript functionalities with AMP components.

3. Disallowed Attribute or Attribute Value Present in HTML Tag

Cause:

Use of non-AMP attributes (e.g., onclick, onmouseover).

Solution:

Remove non-AMP attributes or use AMP alternatives:
Tag Sample:
<button on="tap:AMP.setState({modalOpen: true})">Click Me</button>

Prevention:

Refer to the AMP Attribute Guidelines before implementation.

4. Only amp-boilerplate and amp-custom <style> Tags Are Allowed

Cause:

Custom styles are placed outside <style amp-custom>.

Solution:

Move all custom CSS inside <style amp-custom>:
Code Sample:
<style amp-custom>
body { background: #fff; }
</style>

Prevention:

Make sure all custom styles are placed within <style amp-custom> and avoid using external CSS files.

5. A Mandatory Attribute is Missing from an HTML Tag

Cause:

Certain AMP elements require mandatory attributes (e.g., <amp-img> needs width, height, and layout).

Solution:

Add the missing attributes:
Tag Sample:
<amp-img src="image.jpg" width="500" height="300" layout="responsive"></amp-img>

Prevention:

Follow the AMP Component Documentation.

6. CSS Syntax Error in <span> or <style amp-custom>

Cause:

Invalid CSS rules inside <style amp-custom>

Solution:

Remove or correct invalid CSS properties.

Prevention:

Use AMP CSS Validator to verify correctness.

7. Usage of !important CSS Qualifier is Not Allowed

Cause:

AMP prohibits !important due to style manipulation restrictions.

Solution:

Remove !important and adjust styles accordingly.

Prevention:

Adhere to AMP CSS Restrictions

8. A Tag on This Page Requires an AMP Component <script> Tag, Which is Missing

Cause:

Missing <script> for AMP components used (e.g., <amp-carousel> needs amp-carousel script)

Solution:

Include the required <script> tag inside <head>:
Tag Sample:
<script async custom-element="amp-carousel" src="https://cdn.ampproject.org/v0/amp-carousel-0.2.js"></script>

Prevention:

Check required scripts for each AMP component.

9. Invalid URL Protocol in src or href Attribute

Cause:

Non-secure URLs (http:// instead of https://)

Solution:

Ensure all URLs use the secure HTTPS protocol to comply with AMP guidelines.

Prevention:

Enforce https:// for all resources

10. The Parent Tag of <picture> Must be <noscript>

Cause:

<picture> is used incorrectly in AMP

Solution:

Wrap <picture> inside <noscript>:
Tag Sample:
<noscript>
<picture>
<source srcset="image.jpg" type="image/webp">
</picture>
</noscript>

Prevention:

Follow AMP Guidelines for Images.

11. Tag <amp-story> Has a Disallowed Child Tag

Cause:

Invalid child elements inside <amp-story>

Solution:

Use only allowed elements such as <amp-story-page>, <amp-story-grid-layer>, and <amp-img>

Prevention:

Review the AMP Story Documentation

12. Malformed URL Found in href Attribute of <a> Tag

Cause:

The href attribute contains an invalid URL, such as missing a protocol or malformed structure.

Solution:

Ensure the URL in href is properly formatted, including https://
Tag Sample:
<a href="https://example.com">Valid Link</a>

Prevention:

Validate URLs before adding them to <a> tags
Use AMP Validator to check for errors.

By following these best practices and using AMP-compliant elements, you can prevent

common AMP errors, improve website performance, and maintain a smooth user experience.

Always validate your AMP pages using:

For more details, refer to the AMP Official Documentation.