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.
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.
| Failure | Checker row | Usual fix |
|---|---|---|
| ZIP wraps the creative in a folder | index.html at root | Re-zip from inside the folder |
| No HTML file in the package | Primary HTML found | Re-export with the markup file included |
| No click variable at all | clickTag present | Declare var clickTag = ""; |
| Click variable declared but never opened | clickTag correctly implemented | Open it on a click handler |
| Click opens nothing, or a hard-coded URL | Click-through (tested) · live | Open the variable itself, on a full-size element |
| Dimensions not declared | ad.size meta tag | Add the meta tag to <head> |
| Referenced file missing, mis-cased, or outside the root | All assets present | Exact-case paths, relative to index.html |
Spaces in file names, ?query suffixes on references | File & reference naming | Rename; strip the suffix |
An asset loaded over http:// | HTTPS on all assets | Serve it over https, or package it |
| Assets loaded from outside the ZIP | Self-contained package | Package them locally |
| A required manifest is missing | manifest.json packaged / manifest.js packaged | Add the ad server's manifest |
| Package over the weight cap | File size | Compress and remove unused files |
| Too many files | File count | Combine images; remove unused assets |
| Animation too long, or loops forever | Animation duration · Animation length (measured) · Animation loops forever | Shorten the timeline; set a finite loop count |
| No visible edge on a white page | Border | Add 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:
| Profile | Adds | Package rows |
|---|---|---|
| Generic, Campaign Manager 360 | — | 13 |
| Display & Video 360, Amazon Ad Server (Sizmek), Xandr, Equativ, IAB-style | index.html at root | 14 |
| Google Ads, The Trade Desk | index.html at root, Self-contained package | 15 |
| Adform | index.html at root, manifest.json packaged | 15 |
| Flashtalking | index.html at root, manifest.js packaged | 15 |
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:
- 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.”
- Declared but never opened.
var clickTagsits 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.” - 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.
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.
- Open the ZIP, not the folder.
index.htmlis the first entry, not a directory. No__MACOSXor.DS_Store. - Pick the profile for the ad server it is going to. The click convention, weight cap and required files all change between them.
- Click the ad. The click opens the click variable, not a URL typed into the code, from an element big enough to hit.
- Read the head. One
ad.sizemeta tag with the creative's real width and height. - Search for a leading slash and
../in everysrc,hrefandurl(). Every path is relative to index.html, with the same letter case as the file. - Rename anything with a space and strip
?and#suffixes from asset references. - Search for
http://, then for anyhttps://asset that should be packaged instead. - Check weight and file count against the ad server's cap, not against the last campaign's.
- Watch it to the end. It stops within the limit, loops a finite number of times, and ends on a complete frame.
- Confirm the extras the brief asks for — a border, a backup image, a manifest.
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.
Frequently asked questions
Why does my HTML5 banner work in my browser but get rejected by the ad server?
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?
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?
What does the ad.size meta tag do?
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?
If a banner passes the checker, is it guaranteed to be accepted?
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.