Google Ads HTML5 Validator Errors Explained

Most validator errors fall into a handful of categories: ZIP structure, declared size, click path, external requests and package limits. Here is how to recognise each one and fix it without guessing.

By the PlayableRun team··7 min read

Key takeaways - Most Google Ads HTML5 validator errors come from five areas: ZIP structure, the declared ad size, the click path, external requests, and package limits. - Read the error as a symptom. The same message can come from a nested folder, a stray file, or a script that loads something from outside the ZIP. - Fix one thing at a time and re-upload the exact ZIP each time. Changing several things at once hides the real cause. - Passing the validator is not the same as passing policy review. Test the click-through and the first screen yourself. - Check the current Google Ads specification for exact size and file limits. They change, so this article deliberately quotes no numbers.

What the validator actually checks

When you upload an HTML5 ZIP, Google Ads unpacks it and runs automated checks. It is not judging whether your ad is good. It is asking whether the package is a well-formed, self-contained ad that Google can serve and track safely.

In practice that comes down to four questions:

  • Is there a valid entry HTML file, and are the files in the ZIP allowed types?
  • Does the ad declare the size it is meant to render at?
  • Does it have a click path Google can attach a destination to?
  • Does it keep everything inside the package, rather than pulling code or assets from elsewhere?

Weak creative, confusing copy or a misleading first screen all pass the validator and can still be caught later. For that second stage, see HTML5 Ad Disapproved in Google Ads: Causes and Fixes.

How to read a validator error

Validator messages are short, and the wording changes over time. Do not search for the exact string and apply the first fix you find. Work like this instead:

  1. Decide which category the message belongs to: structure, size, click, external resource, or limits.
  2. Open the ZIP you uploaded, not your project folder, and look at what is actually inside.
  3. Make one fix and rebuild the ZIP.
  4. Upload again and see whether the message changes. A different message means progress.

Step two matters most. Your source folder can be perfect while the archive is wrong, because the wrong folder was zipped or an old build was reused.

Structure errors

These are the most common and the least interesting. They usually mean the validator cannot find what it expects.

No entry HTML file found. The ZIP needs a primary HTML file. The reliable convention is a single index.html at the root of the archive. The usual failure is zipping the parent folder, so the archive contains a folder with index.html inside it instead of index.html at the top. Open the ZIP and look at the first level. If you see one folder and nothing else, re-zip the contents of the folder rather than the folder itself.

More than one HTML file. Leftover test pages, a backup.html or an exported preview page can confuse the check about which file is the ad. Remove everything that is not part of the final ad.

Unsupported or unexpected file types. Source files, design documents, .DS_Store, __MACOSX folders and source maps do not belong in the package. Keep only what the ad loads: HTML, JavaScript, CSS, images, audio and fonts you actually use.

Odd filenames and paths. Spaces, uppercase and lowercase mismatches and special characters cause problems that never show locally, especially on a case-insensitive file system. Use lowercase, hyphens and simple folders, and make sure every path in the code matches the real filename exactly. An image called Hero.png referenced as hero.png works on your laptop and breaks on a server.

For a fuller layout, see HTML5 ZIP for Google Ads: Structure, Assets and Size.

Ad size errors

Display HTML5 ads declare their dimensions in the head of the page using a meta tag named ad.size. Its content holds a width value and a height value, written as width=...,height=... with your real numbers filled in. If the tag is missing, malformed or does not match a supported size, the upload can fail or the ad can render with the wrong layout.

Common causes:

  • The tag is missing because the template came from a general web project, not an ad template.
  • The width and height in the tag differ from the CSS on the root container.
  • The ad was built for one size and uploaded as another.
  • A responsive layout was never given a fixed declared size.

The fix is to decide the size first, declare it, and make the root container match it exactly. Do not rely on the browser window to size the ad. Also remember that how an asset is used differs between classic display and app campaigns, which is covered in Google Ads HTML5 App Campaign: How the Asset Is Used.

Click path errors

A click path error means Google cannot reliably attach a destination to your ad. This matters more than any other category. A playable or banner that cannot send a click anywhere is not a working ad.

Typical causes:

  • No click handler at all. The ad shows a button, but nothing calls the click function.
  • A hard-coded URL. The code uses window.open with a literal address, or sets location.href. Google needs to control the destination so it can count the click and route it, and a hard-coded address bypasses that. Browsers also treat popups opened from script cautiously; the MDN page on window.open explains why.
  • The wrong method for the campaign. Some setups use a clickTag variable and others use the Exit API. Mixing them, or using one where the other is expected, produces errors or dead clicks.
  • A missing script reference. If your code calls the Exit API but the required script is not referenced in the page, the call has nothing to talk to.

Pick the method that matches your campaign type and follow Google's current documentation for it. Then test the real click on the first screen, the end screen and every button in between. The trade-offs between the two methods are laid out in Exit API vs clickTag: Google HTML5 ad click paths.

External request errors

The validator expects the ad to be self-contained. Anything that loads from outside the ZIP is a risk, because Google cannot inspect it and it may change after review.

Look for these in your code and build output:

  • A font loaded from a public font service rather than bundled in the ZIP.
  • A JavaScript library pulled from a content delivery network.
  • Images or video referenced by full web address.
  • Analytics or tracking snippets added by a template.
  • A stylesheet that imports another stylesheet from a remote host.

The fix is to bundle what you need and reference it with relative paths. That is usually easy for fonts and libraries, and harder for tracking code, which usually needs to go through the approved measurement route for your campaign instead of living in the creative.

A quick way to find offenders: open the ad in a browser with the network panel visible and look at every request. Anything that goes to another host is a candidate. Do this with the cache disabled, otherwise you may miss requests that were cached from earlier sessions.

Package limit errors

Errors about size or number of files mean the package is larger or more fragmented than the network allows. I will not quote figures here, because they are updated. Check the current Google Ads specification for HTML5 ads before you build, not after your upload fails.

What helps, whatever the exact limit:

  • Compress images and convert them to efficient formats.
  • Remove unused assets left over from earlier iterations.
  • Subset fonts to the characters you use.
  • Minify scripts and styles, and avoid shipping a full game engine for a short interaction.
  • Replace long audio with short loops or cut it.

Playables feel this more than banners because they carry logic, art and sound. The techniques are covered in How to Reduce Playable Ad File Size Without Losing Polish.

A sensible order for fixing failures

When an upload fails and the message is unclear, go through the categories in order of cheapness:

  1. Structure. Open the ZIP. Is index.html at the root? Is anything extra inside?
  2. Size. Is it declared, and does it match the container?
  3. Click path. Is there exactly one method, and is it wired to every call to action?
  4. External requests. Does anything load from another host?
  5. Limits. Is the package within the current spec?

Each step is quick, and the order matches how often each problem occurs. Keep a log of what you changed and what the validator said afterwards. It saves you from repeating attempts, especially if a colleague takes over.

When the validator passes but the ad still fails

A clean upload is a good sign, not a verdict. Review can still reject an ad for reasons the validator never examines: a click that opens the wrong place, an end screen that hides the call to action, or content that misrepresents the app. Before you launch, preview the ad on a real device, tap everything, and confirm the destination. The Playable HTML5 QA checklist gives a practical order for doing that.

Prevent errors at the source

Most repeat errors come from hand-assembled packages. A template that already has the right structure, size declaration and click wiring removes whole categories of failure. If you build playables from a store listing, PlayableRun generates a Google Ads-ready ZIP, so you start from a package that is already shaped correctly, though you should still run through the checks above.

If you want to see what a finished package looks like, browse the demos, or create a free account and test an export against the validator yourself.

Frequently asked questions

›Why does the Google Ads HTML5 validator reject a ZIP that works locally?

Locally, your browser is forgiving. It resolves paths on a case-insensitive file system, loads remote files freely and does not care about extra folders. The validator checks the archive itself: where the entry file sits, which file types are inside, whether the size is declared, whether the click path is valid and whether anything loads from outside the package.

›What is the most common cause of a missing entry file error?

Zipping the parent folder instead of its contents. The archive then contains one folder with index.html inside it, rather than index.html at the top level. Open the ZIP, check the first level, and re-zip the contents of the folder.

›Does passing the validator mean my ad will be approved?

No. The validator checks technical structure. Policy review looks at the experience: whether the click works, whether the ad is misleading, and whether the content is acceptable. Test the live click path and the first screen yourself.

›Should I use clickTag or the Exit API?

Use the method that matches your campaign type and follow Google's current documentation for it. Mixing the two, or using one where the other is expected, is a common cause of click path errors and dead clicks.

›Where do I find the current file size and file count limits?

In the official Google Ads Help documentation for HTML5 ads. Limits change over time, so check the current spec rather than relying on a number you saw in an old article or forum thread.

Sources

Turn your store listing into a playable

Paste an App Store or Google Play link and get an HTML5 playable you can test in minutes. The first one is free.

Keep reading