Skip to content
Banner production

Why your HTML5 banner gets rejected at upload — and how to catch it first

Most bounced ZIPs fail for one of a handful of reasons: a wrapper folder, a clickTag that is declared but never opened, a missing ad.size tag, a path that leaves the creative folder, a file name with a space in it. None of them show up when you preview the banner on your own machine. Here is what each failure is, why the ad server cares, and how to fix it before you send.

18 November 2026 10 min read Built from the checks in our HTML5 ad validator

1. Why it works locally and fails there

A banner that plays perfectly in your browser can still bounce at upload, and the reason is rarely the animation. Your browser opens the file you point it at. It does not care how the ZIP is structured, whether the click is tracked, or whether a path would resolve from a different server. An ad server cares about all of those, because it has to unpack your creative, serve it from its own location, measure it and count its clicks.

So the failures cluster in the gap between “it plays” and “it can be served”: packaging, click handling, file references and declared metadata. They surprise people because nothing on screen ever looked wrong.

Two kinds of bounce

Packaging, click and metadata problems tend to fail at upload, when the ad server's own validator reads the ZIP. Weight, animation and presentation problems are as often caught later, by a trafficker or a publisher's QA — a slower and more expensive bounce, because by then the set has been delivered and the client has been told it is done.

2. The failures at a glance

This is the list our validator works through. The middle column is the exact name of the row it reports, so you can match a failure here to a line in the result.

Common rejection causes and the row that catches each one in our HTML5 ad validator. Rows marked “live” are measured from the ad running in the preview rather than read from the ZIP.
FailureChecker rowUsual fix
ZIP wraps the creative in a folderindex.html at rootRe-zip from inside the folder
No HTML file in the packagePrimary HTML foundRe-export with the markup file included
No click variable at allclickTag presentDeclare var clickTag = "";
Click variable declared but never openedclickTag correctly implementedOpen it on a click handler
Click opens nothing, or a hard-coded URLClick-through (tested) · liveOpen the variable itself, on a full-size element
Dimensions not declaredad.size meta tagAdd the meta tag to <head>
Referenced file missing, mis-cased, or outside the rootAll assets presentExact-case paths, relative to index.html
Spaces in file names, ?query suffixes on referencesFile & reference namingRename; strip the suffix
An asset loaded over http://HTTPS on all assetsServe it over https, or package it
Assets loaded from outside the ZIPSelf-contained packagePackage them locally
A required manifest is missingmanifest.json packaged / manifest.js packagedAdd the ad server's manifest
Package over the weight capFile sizeCompress and remove unused files
Too many filesFile countCombine images; remove unused assets
Animation too long, or loops foreverAnimation duration · Animation length (measured) · Animation loops foreverShorten the timeline; set a finite loop count
No visible edge on a white pageBorderAdd a 1px border if the placement needs one

Not every row runs on every ad server. The validator has 11 trafficking profiles, and each one adds only the rows its ad server actually demands. On the default Generic profile, reading the ZIP produces 13 rows; one of them, Click URL, is information rather than a verdict. The other profiles add up to two more:

Rows each profile adds to the 13 the Generic profile runs, from the profile definitions in the validator's engine.
ProfileAddsPackage rows
Generic, Campaign Manager 360—13
Display & Video 360, Amazon Ad Server (Sizmek), Xandr, Equativ, IAB-styleindex.html at root14
Google Ads, The Trade Deskindex.html at root, Self-contained package15
Adformindex.html at root, manifest.json packaged15
Flashtalkingindex.html at root, manifest.js packaged15

This article deliberately does not repeat each ad server's weight and animation limits — the validator shows the ones it applies on screen, beside the profile you pick. For the platforms' own figures, see our ad specs cheat sheet.

3. The ZIP itself

The wrapper folder is the single most common packaging rejection, and it is invisible from inside your project. You select the folder banner_300x250, choose Compress, and get a ZIP whose only top-level entry is that folder. The ad server opens the ZIP, looks for index.html at the top level, and finds a directory instead.

# wrong: index.html ends up at banner_300x250/index.html inside the ZIP
zip -r banner_300x250.zip banner_300x250

# right: zip the folder's contents, from inside it, without Finder metadata
cd banner_300x250
zip -r -X ../banner_300x250.zip . -x "*.DS_Store"

Check the result by listing it (unzip -l banner_300x250.zip). The first line should be index.html, not a folder name.

Our validator judges this on the ZIP exactly as you packed it. When it fails, the row names the folder it found — “index.html is inside the folder … the zip wraps the creative instead of holding it at the top level” — so you know the problem is the packing and not the file. The row runs on every profile except Generic and Campaign Manager 360.

Finder leftovers — __MACOSX/, .DS_Store, ._ files, Thumbs.db — add weight and files the ad server did not ask for. The validator ignores them when it reads the package, and its repackager offers to strip them.

A required manifest is the other packaging failure, and it only applies to some ad servers. Adform reads the banner definition from a manifest.json in the package root; Flashtalking's current API loads a manifest.js from beside index.html (older ftClick builds ship ftLocal.html instead, which the validator also accepts).

4. The click-through

An ad server that tracks clicks needs the banner to hand every click to it. The standard way is a clickTag variable that the server fills at serve time with its tracked URL. There are three distinct ways to get this wrong, and they need different fixes:

  1. No click variable. The banner may still be clickable, but there is nothing for the ad server to fill. The validator's row reads “No clickTag found.”
  2. Declared but never opened. var clickTag sits in the head, but nothing calls it — usually because a template was copied and the click handler was not. The row reads “clickTag is defined but not used on a clickable element.”
  3. The click opens a hard-coded URL. This is the dangerous one, because it looks as if it works. The visitor lands on the right page; the ad server never sees the click.
<head>
  <meta name="ad.size" content="width=300,height=250">
  <script>var clickTag = "";</script>   <!-- the ad server fills this -->
</head>
<body>
  <div id="ad"> … </div>
  <script>
    document.getElementById('ad').addEventListener('click', function () {
      window.open(window.clickTag);
    });
  </script>
</body>
<!-- each of these bypasses the ad server's click tracking -->
<a href="https://www.example.com/offer">…</a>
window.open("https://www.example.com/offer");

// declared, and then nothing ever opens it
var clickTag = "https://www.example.com/offer";

A default URL in the declaration is fine; the ad server overwrites it at serve time. What matters is that the click opens the variable.

The validator checks the first two from the package. It looks only at code the browser actually runs — script bodies, tag attributes and .js files, with comments stripped — so a headline that happens to contain the word “clickTag”, or a commented-out handler, does not count as a pass.

The third it checks by doing what a visitor would. In a hidden copy of the creative it hovers and clicks up to eight clickable elements, largest first, and records what opened, without ever leaving the page. If nothing opens, the row fails: “nothing opened. The click-through never fires.” If the banner sets a clickTag value and the click opens some other URL, it warns that “The ad server's click tracking would be bypassed.” A script error on hover or click is a fail too, because a click that throws may never reach the ad server.

Not every ad server uses clickTag. Adform expects clickTAG through its DHTML runtime; Flashtalking's current API wires exits with myFT.applyClickTag(); Studio creatives exit through Enabler.exit(). The validator judges each convention under the profile that uses it, so a correct Flashtalking build is not marked broken for lacking a Google-style variable. The exact syntax for each platform is in our HTML5 banner production guide.

5. Paths, names and the ad.size tag

Paths that leave the creative folder. On a local server, /img/logo.png resolves to your project. Once the ad server hosts the creative in its own folder, a path starting with / points at the root of its domain, and ../ from index.html climbs out of the creative entirely. Both load nothing, even when a file of that name is in the ZIP.

<img src="/img/logo.png">   <!-- root-relative: escapes the creative -->
<img src="../logo.png">     <!-- climbs above index.html -->
<img src="img/logo.png">     <!-- relative to index.html: correct -->

The validator's All assets present row collects every reference in the HTML, CSS and JavaScript, then fails on any that is missing from the ZIP or that escapes the root, listing which. It compares paths exactly, so Logo.PNG referenced as logo.png shows up as missing — which is right, because most servers that host creatives treat file names case-sensitively even though a Mac usually does not.

Spaces and cache-busters. Ad servers can reject, or fail to load, files whose names contain spaces, and references that carry a ?query or #fragment suffix the packaged file does not have. The suffix usually comes from the authoring tool: an Animate export can reference its art as main_bg.jpg?1503778967704. The File & reference naming row reports both. The repackager will strip a suffix, but only where the bare file name is genuinely in the package.

The ad.size tag. One line in <head> declares the creative's dimensions — the first line of the click example above. Our validator fails the package if the tag is missing, or if it is there but the width and height cannot be read. Its repackager can insert the tag, but only when it can measure the creative from somewhere real: an existing tag, a size such as 300x250 in the ZIP or folder name, or the creative's canvas. If it cannot measure, it says so and inserts nothing.

6. External requests

Two separate problems sit under this heading. The first applies everywhere: any asset loaded over plain http:// is mixed content on a secure page, and browsers block it. The HTTPS on all assets row runs on every profile. It deliberately ignores click destinations — the default landing page in an Animate export, or an <a href>, is somewhere the visitor goes, not something the browser fetches.

The second is stricter: some ad servers want the creative to be entirely self-contained. On the Google Ads and The Trade Desk profiles the validator adds a Self-contained package row, which fails on anything fetched from outside the ZIP — src and poster attributes, <link href> and CSS url(). It allows the library hosts Google serves itself for Studio and Animate output, and does not count click destinations as requests. A web font linked from a font service is a common example; package the font file, or use a system font.

7. Weight, file count and animation

These are numbers, so you can see them coming. The File size row compares the ZIP you dropped with the cap of the profile you picked; File count does the same for the number of files. On the Display & Video 360 profile there is no fixed package cap, so the weight is reported for information and not scored. The platforms' own limits are in the specs cheat sheet, and the techniques for getting under them are in our file-size guide — neither is repeated here.

If a package is over, the validator's repackager can do the mechanical part: remove files nothing refers to, and step JPEG quality down until the ZIP gets under the cap. Formats, file names and image dimensions never change, and the result is re-validated so the improvement is shown rather than claimed.

Animation length is checked twice. From the package, the validator estimates the timeline from an Animate-style frame count, and says so — the estimate is approximate, and the loop count cannot be read from the files at all. From the running preview, it measures CSS and Web Animations timings and a CreateJS timeline directly, and warns separately if a CSS or Web Animations animation is set to loop forever. A measured figure over the profile's cap is a fail, because it is not an estimate.

The border is a warning, not a fail: some placements require a 1px border so the ad's edge shows against a white page. If no CSS border is found in the package and the creative draws into a canvas, the validator reads the canvas edge in the preview before it reports one missing.

8. What a package check cannot see

A blank banner passes every check on the list above. So does one whose headline is cut off, or whose images 404 because of a typo in a script. These are the failures a trafficker or a client finds afterwards. The validator runs the ad in a live preview and measures it twice, at about 1.5 and 3.6 seconds, so an ad that fades in is not reported blank at its first frame:

  • Images load — every image actually decoded.
  • Renders content — something visible was painted. A canvas creative is read back on a sampling grid; one flat value at every sampled point is a blank canvas, not a pass.
  • Legible text size — warns on text rendering under 9px.
  • Text fits its box and Copy inside the frame — copy clipped by its container, or pushed past the edge of the ad.
  • Text contrast — the lowest WCAG contrast ratio found, against the AA threshold for that text size.
  • Clickable surface — a clickable element exists and at least one is 32×24 or larger.

When a creative draws its copy into a <canvas>, the text rows are reported as skipped rather than passed, because there is no text in the page to measure. And these live findings are kept out of the score on purpose: the score and the verdict come from the package checks alone.

What the validator does not check

There is no backup-image check. Many ad servers want a static backup for each size; the validator will not tell you one is missing. Its repackager can generate one — it holds the ad on its last frame and captures a full-size JPG to bundle beside the ZIP — but whether the brief needs it is still yours to confirm.

The Google Ads and Campaign Manager 360 profiles carry Google's own published limits. The others are our own defaults, printed on screen so you can judge them. Re-check against the ad server's current spec before treating a pass as a guarantee.

9. The pre-upload checklist

Run every size through this before anything leaves your desk. Each line is a failure from this article, in the order it tends to bite.

  1. Open the ZIP, not the folder. index.html is the first entry, not a directory. No __MACOSX or .DS_Store.
  2. Pick the profile for the ad server it is going to. The click convention, weight cap and required files all change between them.
  3. Click the ad. The click opens the click variable, not a URL typed into the code, from an element big enough to hit.
  4. Read the head. One ad.size meta tag with the creative's real width and height.
  5. Search for a leading slash and ../ in every src, href and url(). Every path is relative to index.html, with the same letter case as the file.
  6. Rename anything with a space and strip ? and # suffixes from asset references.
  7. Search for http://, then for any https:// asset that should be packaged instead.
  8. Check weight and file count against the ad server's cap, not against the last campaign's.
  9. Watch it to the end. It stops within the limit, loops a finite number of times, and ends on a complete frame.
  10. Confirm the extras the brief asks for — a border, a backup image, a manifest.
Check it before the ad server does

Drop the ZIP in. Every row above, in seconds.

Pick the ad server's profile and get the package checks, a live preview with the click tested, and a score. Free with no signup — 2 checks a day without an account, 5 with a free one. Your ZIP never leaves your browser.

Open the validator

Frequently asked questions

Why does my HTML5 banner work in my browser but get rejected by the ad server?
Because your browser is forgiving in ways an ad server is not. A local preview opens the file you double-clicked, so it never notices that index.html sits inside a folder in the ZIP. A Mac's file system usually ignores letter case, so Logo.png and logo.png look like the same file on your machine and different files on the server. A root-relative path such as /img/logo.png resolves on a local server and points at nothing once the creative is served from the ad server's own folder. And a banner with no clickTag still plays perfectly — it just has nothing for the ad server to track.
What is a clickTag, and why does the ad server need one?
A clickTag is a variable in the creative that the ad server fills in at serve time with its own tracked click URL. The banner's click handler opens that variable instead of a hard-coded address, so every click passes through the ad server's tracking before it reaches the landing page. Declare it (var clickTag = "";) and open it on click (window.open(window.clickTag)). Not every ad server uses the name: Adform expects clickTAG, Flashtalking's current API uses myFT.applyClickTag(), and Studio creatives exit through Enabler.exit().
Why does the ad server say index.html is missing when it is in my ZIP?
Almost always because the ZIP holds a folder that holds index.html, rather than holding index.html itself. That happens when you compress the folder instead of its contents. Open the ZIP: if the first thing you see is a folder, re-zip from inside it so index.html sits at the top level.
What does the ad.size meta tag do?
It tells the ad server the creative's width and height: a meta tag named ad.size with the content width=300,height=250, placed in the head of index.html. Without it the server has to guess the dimensions from elsewhere, and Google's HTML5 specifications ask for it. Our checker fails a package that lacks it, or whose tag it cannot read, on every profile.
Can I check a banner before I upload it, for free?
Yes. Our HTML5 ad validator runs in your browser and nothing is uploaded. Every check, the score and the verdict are free with no signup — 2 checks a day without an account, 5 with a free one. Downloading the PDF report or a repackaged ZIP needs a free account. PRO ($35/mo or $280/yr) removes the daily cap and checks a whole batch of sizes in one grid.
If a banner passes the checker, is it guaranteed to be accepted?
No, and we would rather say so. The Google Ads and Campaign Manager 360 profiles carry Google's own published limits; the other profiles use our own sensible defaults, shown on screen. The click patterns for non-Google ad servers are written from their documented conventions. The checker does not look for a backup image, and platforms change their rules. Treat a pass as the end of the avoidable failures, not as a promise about someone else's validator.

Catch the bounce before you send.

Validate an HTML5 banner ZIP against the ad server it is going to, free in your browser — or hand the build to the team that produces trafficking-ready banners for agencies every day.