VAST Inspector Guide

Introduction to VAST and Why Inspection Matters

The Video Ad Serving Template, commonly known as VAST, is the IAB standard that defines how video ad servers communicate with video players. Every time a pre-roll, mid-roll, or post-roll ad plays in a streaming player or on a publisher's website, a VAST XML document is exchanged behind the scenes. That document carries everything the player needs: the creative media files, tracking pixels, click-through URLs, companion banners, and metadata about the ad itself.

Because VAST tags often pass through multiple ad servers, demand-side platforms, and supply-side platforms before reaching the player, small errors compound quickly. A missing required element, an incorrect MIME type, or a broken wrapper chain can cause the ad to fail silently, costing revenue and frustrating campaign teams. The VAST Inspector tool gives you a way to catch those problems before they reach production by letting you parse, validate, and preview any VAST tag in a controlled environment.

Entering Tags: URL vs. Raw XML

The VAST Inspector accepts two input modes. The first is a VAST tag URL, which is the most common format you will encounter in trafficking sheets and ad server UIs. Paste the full URL, including any macros such as[TIMESTAMP] or [CACHEBUSTING], and the tool will fetch the XML response from the server in real time. This mode is ideal when you want to verify what a live endpoint actually returns, including any server-side logic that modifies the response based on query parameters.

The second mode is raw XML input. Switch to the XML tab and paste the full VAST document directly. This is useful when you have already captured the XML from a network trace, received it in an email, or exported it from another debugging tool. Raw XML mode bypasses the network fetch entirely and analyzes the document as provided, which means you can inspect offline or test modified versions of a tag without deploying changes to your ad server.

Regardless of the input mode, you can optionally select a target VAST version — 2.0, 3.0, 4.0, 4.1, 4.2, or Auto. When set to Auto, the inspector reads the version attribute from the root VAST element and validates against that version's specification. Choosing a specific version is helpful when you need to confirm that a tag is forward-compatible or when you are migrating creatives from one VAST version to another.

Understanding the Analysis Panel

Ad Structure

After clicking Analyze, the first section of the results displays the overall ad structure. This tree view shows whether the tag is an InLine ad, a Wrapper, or a combination through nested wrappers that eventually resolve to an InLine. Each node in the tree lists the Ad ID, the ad system name, and the creative type. If the document contains multiple Ad elements — common in ad pod scenarios — each one appears as a separate branch. Reviewing this tree helps you quickly confirm that the tag returns the expected number of ads and that the hierarchy matches your trafficking setup.

Media Files

The media files panel enumerates every MediaFile element found in the VAST document. For each file, the inspector displays the delivery method (progressive or streaming), the MIME type (such as video/mp4 or video/webm), the bitrate, the resolution, the codec if specified, and the direct URL. This panel is essential for verifying that your creative includes the right mix of formats and bitrates to cover desktop, mobile, and connected-TV environments. A common pitfall is providing only a single high-bitrate MP4, which forces low-bandwidth users into buffering or playback failure.

Tracking Events

The tracking events section lists every Tracking, Impression, ClickTracking, and Error pixel found in the tag. Events are grouped by type — impression, start, firstQuartile, midpoint, thirdQuartile, complete, and others — so you can verify at a glance that all required measurement points are present. Missing a midpoint tracker, for example, means your reporting will lack a key viewability metric. The inspector also flags duplicate tracking URLs, which can inflate event counts in your analytics.

Wrapper Chains

When the VAST tag is a Wrapper, the inspector follows the VASTAdTagURI to the next server and repeats the analysis. The wrapper chain visualization shows each hop as a separate card, displaying the server domain, the response time, the VAST version returned, and whether the hop succeeded or failed. Long wrapper chains — five or more hops — are a red flag because each hop adds latency and increases the chance of timeout. The IAB recommends keeping chains to three hops or fewer. If you see unexpected domains in the chain, it could indicate unauthorized reselling or misconfigured demand paths.

Reading the Event Log (IMA SDK Events)

When you switch to Preview mode and play the ad, the VAST Inspector records every event dispatched by the Google IMA SDK in a real-time event log. These events include LOADED, STARTED, FIRST_QUARTILE, MIDPOINT, THIRD_QUARTILE, COMPLETE, ALL_ADS_COMPLETED, and error events. Each entry shows a timestamp, the event name, and associated metadata such as the ad ID and creative ID.

The event log is invaluable for confirming that tracking fires match what the player experiences. If the ad plays to completion but you never see a COMPLETE event, the issue likely lies in the creative's duration metadata or a conflict between the VAST duration element and the actual media file length. Similarly, if you see an AD_ERROR event, the log will include an error code that maps directly to the VAST error code table, giving you a specific starting point for debugging.

Strict Schema Validation

Beyond ad-serving validation, the VAST Inspector offers a strict schema mode that checks the XML against the official IAB XSD for the selected VAST version. This mode catches structural issues that would not necessarily prevent playback but violate the specification — for example, elements in the wrong order, unsupported attributes, or missing optional-but-recommended fields like AdTitle or Description.

Strict validation is especially important when your tags will be consumed by players or verification vendors that enforce the spec rigorously. Some SSPs reject tags that fail schema validation outright, which means a tag that "works in testing" might still be blocked in production. Running strict validation before launch eliminates that risk. Note that macro placeholders like [ERRORCODE] and [CONTENTPLAYHEAD] will trigger schema warnings because they are not valid URIs; this is expected and can be safely ignored as long as the macros are standard IAB macros.

Preview Mode

Once your tag passes analysis, the Preview tab becomes available. Preview mode renders the ad in an embedded video player using the Google IMA SDK, simulating a real playback environment. You can watch the creative play, verify click-through behavior, and observe companion banners if present. The player respects the ad's skip offset if one is defined, so you can confirm that the skip button appears at the correct time.

Preview should always follow a successful analysis. Playing a tag with known errors can produce misleading results — the player might silently fall back to a default behavior that masks the underlying problem. Treat preview as a final confirmation step rather than a first debugging tool.

Common VAST Error Codes

When a video player encounters a problem with a VAST tag, it fires an error event with a numeric code defined by the IAB specification. Understanding these codes is critical for fast troubleshooting. The table below covers the most frequently encountered error codes.

When you encounter one of these codes in the VAST Inspector's event log, cross-reference it with the analysis panel results. For example, a 301 error paired with a long wrapper chain in the analysis view confirms that latency is the root cause rather than a missing creative.

Best Practices for VAST Debugging

• Validate early and often. Run every new tag through the inspector before trafficking it into your ad server. Catching errors before launch prevents revenue loss and reduces fire drills.
• Use strict schema validation for programmatic channels. Many SSPs and verification vendors enforce the IAB XSD. A tag that plays correctly in your test player may still be rejected upstream.
• Keep wrapper chains short. Aim for three hops or fewer. Each additional hop adds latency and increases the chance of timeout errors (code 301) or hitting the wrapper limit (code 302).
• Provide multiple media file formats. Include at least an MP4 and a WebM rendition at two or more bitrates. This ensures coverage across browsers, mobile devices, and connected-TV platforms.
• Verify tracking completeness. Confirm that impression, start, quartile, and complete trackers are all present. Missing trackers lead to incomplete reporting and can affect billing reconciliation.
• Test macros separately. Macro placeholders will fail strict schema checks. Verify macros are replaced correctly by fetching the tag URL with realistic parameter values and inspecting the resolved XML.
• Preview after analysis. Always resolve analysis errors before moving to preview. Playing a broken tag can mask issues behind player fallback behavior.
• Document your findings. Use the inspector's export functionality or take screenshots of the analysis and event log. Sharing clear evidence with ad ops and engineering teams accelerates resolution.