AMP Implementation Issues | Blue Frog Docs

AMP Implementation Issues

Diagnose and fix Accelerated Mobile Pages (AMP) validation errors and implementation issues

AMP Implementation Issues

What This Means

Accelerated Mobile Pages (AMP) is an open-source HTML framework designed to create fast-loading mobile web pages. AMP pages are stripped-down versions of regular HTML pages that load almost instantly on mobile devices.

Important Note About AMP in 2025

AMP's Role Has Changed:

  • Google no longer requires AMP for Top Stories carousel
  • AMP no longer provides ranking boost
  • Core Web Vitals are now more important than AMP
  • Many publishers are moving away from AMP to standard responsive pages

When AMP Still Makes Sense:

  • High-traffic news and content sites
  • Sites struggling with mobile performance
  • Publishers wanting instant-loading content
  • Email newsletters (AMP for Email)

Modern Alternative:

  • Focus on Core Web Vitals instead
  • Optimize regular pages to load as fast as AMP
  • Use responsive design with performance best practices

Impact on Your Business

When AMP Is Beneficial:

  • Near-instant page loads on mobile
  • Reduced server load and bandwidth costs
  • Improved mobile user experience
  • Better mobile engagement metrics

When AMP Causes Problems:

  • Limited design and functionality
  • Tracking and analytics complications
  • Maintenance overhead (two versions)
  • Advertising limitations
  • Reduced revenue for some publishers

Common Causes

AMP Validation Errors

<!-- Invalid: Regular HTML in AMP -->
<img src="image.jpg" alt="Image">
<!-- Must use: -->
<amp-img src="image.jpg" alt="Image" width="600" height="400"></amp-img>

<!-- Invalid: Custom JavaScript -->
<script src="custom.js"></script>
<!-- AMP doesn't allow custom JS -->

<!-- Invalid: Inline styles -->
<div style="color: red;">Text</div>
<!-- Must use CSS in <style amp-custom> -->

Missing Required AMP Components

<!-- Missing: Canonical link -->
<link rel="canonical" href="https://example.com/article">

<!-- Missing: AMP boilerplate -->
<style amp-boilerplate>...</style>

<!-- Missing: AMP script -->
<script async src="https://cdn.ampproject.org/v0.js"></script>

Incorrect AMP HTML Structure

<!-- Wrong doctype -->
<!DOCTYPE html>
<!-- Must be: -->
<!doctype html>

<!-- Missing AMP attribute -->
<html lang="en">
<!-- Must be: -->
<html ⚡ lang="en">
<!-- Or: -->
<html amp lang="en">

Analytics and Tracking Issues

<!-- Regular Google Analytics (doesn't work in AMP) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>

<!-- Must use AMP Analytics component -->
<amp-analytics type="gtag">...</amp-analytics>

How to Diagnose

Method 1: AMP Validator

  1. Visit AMP Validator
  2. Enter your AMP URL
  3. Click "Validate"
  4. Review all errors and warnings

What to Look For:

  • Red errors (must fix)
  • Yellow warnings (should fix)
  • Specific line numbers for issues
  • Suggested fixes

Method 2: Chrome DevTools Console

  1. Add #development=1 to your AMP URL
    • Example: https://example.com/article/amp#development=1
  2. Open Chrome DevTools (F12)
  3. Go to Console tab
  4. Look for AMP validation messages

What to Look For:

AMP validation successful.

Or:

Powered by AMP ⚡ HTML – Version 2312345678910
AMP validation had errors:
- The tag 'img' may only appear as a descendant of tag 'noscript'...

Method 3: Google Search Console

  1. Open Google Search Console
  2. Go to "AMP" report (under "Enhancements")
  3. Review AMP status
  4. Check for validation errors

What to Look For:

  • Number of valid AMP pages
  • Error types and affected pages
  • Validation error trends
  • Pages removed from AMP coverage

Method 4: AMP Test Tool

  1. Visit Google AMP Test
  2. Enter your AMP URL
  3. Click "Test URL"
  4. Review results

What to Look For:

  • "Valid AMP page" status
  • Specific errors with code examples
  • Preview of how page renders
  • Structured data validation

Method 5: Browser Extension

Install AMP Validator Extension:

  1. Install extension
  2. Visit AMP page
  3. Click extension icon
  4. View validation status (green/red)

General Fixes

Fix 1: Convert Regular HTML to AMP HTML

Basic AMP Template:

<!doctype html>
<html ⚡ lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
  <title>Page Title</title>

  <!-- Canonical link to regular version -->
  <link rel="canonical" href="https://example.com/article">

  <!-- AMP Runtime -->
  <script async src="https://cdn.ampproject.org/v0.js"></script>

  <!-- AMP Boilerplate -->
  <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>

  <!-- Custom Styles -->
  <style amp-custom>
    /* Your CSS here (max 75KB) */
    body { font-family: sans-serif; }
    .container { max-width: 800px; margin: 0 auto; }
  </style>
</head>
<body>
  <article>
    <h1>Article Title</h1>
    <p>Content...</p>
  </article>
</body>
</html>

Fix 2: Replace Standard HTML Elements with AMP Components

Images:

<!-- Regular HTML -->
<img src="image.jpg" alt="Image">

<!-- AMP -->
<amp-img src="image.jpg" alt="Image" width="600" height="400" layout="responsive"></amp-img>

Videos:

<!-- Regular HTML -->
<video src="video.mp4" controls></video>

<!-- AMP -->
<amp-video src="video.mp4" width="640" height="360" layout="responsive" controls>
  <div fallback>Your browser doesn't support HTML5 video</div>
</amp-video>

YouTube Embed:

<!-- Regular HTML -->
<iframe src="https://www.youtube.com/embed/VIDEO_ID"></iframe>

<!-- AMP -->
<script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"></script>
<amp-youtube data-videoid="VIDEO_ID" width="480" height="270" layout="responsive"></amp-youtube>

Iframes:

<!-- AMP -->
<script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>
<amp-iframe src="https://example.com/embed" width="600" height="400" sandbox="allow-scripts allow-same-origin" layout="responsive">
  <div placeholder>Loading...</div>
</amp-iframe>

Fix 3: Implement AMP Analytics

Replace regular analytics with AMP Analytics:

<!-- Include AMP Analytics component -->
<script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script>

<!-- Google Analytics 4 -->
<amp-analytics type="gtag" data-credentials="include">
  <script type="application/json">
  {
    "vars": {
      "gtag_id": "G-XXXXXXXXXX",
      "config": {
        "G-XXXXXXXXXX": {
          "groups": "default"
        }
      }
    }
  }
  </script>
</amp-analytics>

<!-- Google Analytics Universal -->
<amp-analytics type="googleanalytics">
  <script type="application/json">
  {
    "vars": {
      "account": "UA-XXXXX-Y"
    },
    "triggers": {
      "trackPageview": {
        "on": "visible",
        "request": "pageview"
      }
    }
  }
  </script>
</amp-analytics>

Fix 4: Add Structured Data

Include JSON-LD structured data:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "Article Headline",
  "image": ["https://example.com/image.jpg"],
  "datePublished": "2025-01-15T08:00:00+00:00",
  "dateModified": "2025-01-15T09:20:00+00:00",
  "author": {
    "@type": "Person",
    "name": "John Doe"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Publisher Name",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  }
}
</script>

On Regular Page:

<link rel="amphtml" href="https://example.com/article/amp">

On AMP Page:

<link rel="canonical" href="https://example.com/article">

Fix 6: Handle Forms in AMP

<!-- Include form component -->
<script async custom-element="amp-form" src="https://cdn.ampproject.org/v0/amp-form-0.1.js"></script>

<form method="post" action-xhr="https://example.com/subscribe" target="_top">
  <input type="email" name="email" required>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Thanks for subscribing!
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Subscription failed. Please try again.
    </template>
  </div>
</form>

Fix 7: Common Validation Fixes

Remove Disallowed Elements:

<!-- Remove all custom JavaScript -->
<!-- Remove <base> tag -->
<!-- Remove <frame> and <frameset> -->
<!-- Remove <object>, <param>, <applet>, <embed> -->
<!-- Remove <form> with non-HTTPS action -->
<!-- Remove inline event handlers (onclick, etc.) -->

Fix CSS Issues:

<!-- All CSS must be in <style amp-custom> -->
<!-- Max 75KB of CSS -->
<!-- No !important declarations on animations -->
<!-- No external stylesheets -->

Platform-Specific Guides

Detailed implementation instructions for your specific platform:

Platform Platform Guide
WordPress WordPress Guide - Use AMP plugin for implementation
Shopify Shopify Guide - Check app store for AMP solutions
Custom CMS Follow official AMP documentation

Testing & Validation

After implementing or fixing AMP:

Step 1: Validate AMP

  1. Visit AMP Validator
  2. Enter your AMP URL
  3. Verify "PASS" status
  4. Fix any remaining errors

Step 2: Test in Google Search Console

  1. Open Search Console
  2. Use URL Inspection tool
  3. Enter AMP URL
  4. Click "Test live URL"
  5. Verify "Valid AMP page"

Step 3: Preview AMP

  1. Visit your AMP page
  2. Append #development=1 to URL
  3. Open DevTools console
  4. Verify: "AMP validation successful"

Step 4: Test Analytics

  1. Visit AMP page
  2. Open Google Analytics Real-Time report
  3. Verify pageview is tracked
  4. Check events fire correctly

Step 5: Performance Testing

  1. Run PageSpeed Insights on AMP URL
  2. Compare scores to regular version
  3. Verify AMP loads faster
  4. Check Core Web Vitals

Common Mistakes

  1. Using regular <img> instead of <amp-img> - Validation fails
  2. Missing width/height on images - Required for AMP
  3. Inline styles - Must use <style amp-custom>
  4. Custom JavaScript - Not allowed in AMP
  5. Missing amp attribute on <html> - Not recognized as AMP
  6. No canonical link - Breaks search indexing
  7. External stylesheets - Must inline CSS
  8. Exceeding 75KB CSS limit - Validation error
  9. Not testing in AMP validator - Deploy broken AMP
  10. Forgetting amp-analytics - Lose tracking data

AMP vs. Modern Alternatives

Consider Standard Optimization Instead:

When to Use Standard Pages:

  • You can achieve LCP < 2.5s without AMP
  • You need custom JavaScript functionality
  • You want design flexibility
  • You need complex forms or interactions
  • You have adequate development resources

How to Match AMP Performance:

  1. Optimize images (WebP, responsive, lazy loading)
  2. Minimize JavaScript
  3. Inline critical CSS
  4. Use CDN
  5. Enable compression
  6. Optimize server response time
  7. Implement resource hints

Result: Standard pages can match AMP speed with good optimization

Further Reading

↑ Back to top
// SYS.FOOTER