- Published
- Nov 1, 2026
- Reading time
- 11 min read
VAST Macros Not Resolving: Inspect the Actual Request
Trace VAST macros from tag templates to emitted requests and receiver values. Diagnose substitution ownership, unsupported placeholders and encoding errors.

In this guide (10 sections)
To see what a VAST macro became, inspect the HTTP request made by the system responsible for substitution. Compare its actual URI with the template that system received and, where available, the receiver's parsed value. A placeholder in saved VAST can be expected before substitution; a placeholder surviving into the request needs a different investigation.
For browser-side requests, Chrome's Network panel can expose the emitted URI. For server-side ad insertion, obtain the corresponding server evidence. Browser traffic alone cannot show an HTTP call made elsewhere. Preserve both the encoded representation and the decoded value before changing tags.
Two older questions reveal the diagnostic gap#
An archived ad-operations question asks whether populated VAST macros can be viewed. A reply recommends filtering browser Network requests. That is a useful starting point, but it leaves substitution ownership, server-side requests and receiver interpretation unexplained.
A 2016 Stack Overflow question about Google IMA tracking macros asks how to reproduce several SDK-specific placeholders outside IMA. The discussion does not supply a complete authoritative replacement contract. Inferring a private field's meaning from its name or one observed URL would create a new uncertainty.
These are older evergreen questions, not evidence of a fresh SDK outage. This guide uses official references checked on 1 November 2026 to diagnose supported substitutions. It does not reverse-engineer undocumented IMA telemetry or prescribe a replacement SDK.
Record the VAST substitution path.
Use the checklist to compare the template with the request made by the substituting system.
Use the tracking QA checklistOpens a practical guide. No email required.
1. Establish which URI and substitution layer you mean#
A video delivery path can contain an initial ad request, wrapper requests, a media request and event-specific tracking requests. A value visible in one does not establish what another contained. Begin with one failing field in one named request.
The VAST 4.3 macro section assigns substitution responsibility to the party performing the HTTP request. That is often the player; an SSAI server can act instead. Record this owner before asking someone to edit a tag.
| Boundary | Evidence to retain | Question it answers |
|---|---|---|
| Trafficked template | Version and original placeholder spelling | What was configured? |
| VAST response or wrapper | Exact URI delivered to the next actor | What did that actor receive? |
| Substitution actor | Player, SDK, server or agreed vendor layer | Who had the value and responsibility? |
| Emitted request | Actual encoded URI, time and context | What was attempted? |
| Receiver | Parsed field and campaign association, if exposed | What was interpreted? |
Add a request-local identifier only if your integration actually provides one. Preserve campaign and creative identifiers where available, without inventing a join between unrelated requests. Record wall-clock timezone for cross-system matching and elapsed time for local ordering.
For a mixed path, the SSAI ownership guide helps identify which system requests ads and fires each event. Avoid assigning every substitution to the browser simply because the content plays there.
2. Identify the macro's namespace and supported context#
Square brackets alone do not prove that a token is an IAB macro. A template may also contain ad-server macros, integration-specific variables or proprietary SDK fields. Give each token a documented owner and definition.
The current IAB macro registry data records each macro's meaning, context, type and support conditions. For example, ERRORCODE belongs to error tracking URIs. PAGEURL describes the top-level page and has context-dependent support and unavailable-value rules. Their appearance in one list does not make them interchangeable fields.
Google's Ad Manager macro reference uses its own syntax and case-sensitive names. It also distinguishes automatic insertion for recognized third-party tags from manual configuration in custom creatives and templates. Verify that the saved field is processed by the expected ad-server layer.
Likewise, consult the IMA platform compatibility reference for the actual integration. A broad “VAST supported” label does not prove support for every macro, optional feature or undocumented SDK-specific token. Ask the responsible vendor for the exact supported contract when its public references do not answer that field's behavior.
Write “definition or support unverified” in the worksheet when necessary. Guessing that an abbreviation means a Unix timestamp, advertising identifier or volume value is not a safe repair. Preserve the uncertainty and the original field instead of turning one historical example into an implementation rule.
3. Capture one authorized runtime attempt#
Use a supported test page, test inventory or another explicitly authorized diagnostic environment. Open the Network panel before the attempt. Narrow the capture to the relevant host or path, while retaining enough surrounding activity to identify wrappers and redirects.
Chrome's Network tutorial describes filtering, response inspection and request initiators. Inspect the relevant VAST response, then follow the outgoing request that contains the field. If the target event has not occurred, the absence of its request does not prove that macro replacement failed.
The Network reference documents Preserve log across page loads and the Payload tab's source and decoded views. Save which view you inspected. A UI showing [PAGEURL] might be displaying a decoded representation of percent-encoded brackets; that still does not establish a resolved page value.
Keep the raw encoded request separately from a readable diagnostic copy. Do not repeatedly decode the evidence until it resembles the value you expected. Each transformation should state which boundary requires it and what changed.
For SSAI or other server-owned calls, request the equivalent outbound trace from that owner. A missing browser request is not proof of a missing server request. If outbound or receiver logs are unavailable, mark the boundary unobserved rather than assigning it a successful status.
Do not replay impression, click or completion URLs to populate a report. Replaying can create additional attempts and obscure the original sequence. Reading a captured request and testing string transformations locally are different actions from sending it again.
4. Separate substitution failure from encoding failure#
A resolved value can still be encoded incorrectly. Conversely, a perfectly URL-encoded placeholder can remain unresolved. Check these independently.
VAST 4.3 specifies component encoding for replacement values. For array-valued macros, encode the individual values while retaining the comma separator. Its unavailable-value rules distinguish unknown from policy-withheld information and warn against applying a blanket replacement to arbitrary unknown tokens.
Use the current macro's own definition for applicability and special values. Do not fill a privacy-withheld field with a guessed identifier, copy an unrelated campaign's value or replace every unknown token with -1. Such a change can make a URL look tidy while misrepresenting the evidence.
Nested URLs need a boundary-specific contract. Google's custom-creative macro guide explains escaped, unescaped and double-escaped variants for its supported click workflows. That is not a universal rule that every VAST URL must be encoded twice. Count actual embedding and decoding boundaries instead of selecting the most escaped-looking form.
Worked encoding example: a value containing a URL#
This is a hypothetical string exercise. The hostname is illustrative; do not send requests to reproduce it. Suppose a receiver expects a query parameter named page containing this complete value:
https://example.invalid/watch?episode=7&mode=full
As one query-parameter value, component encoding produces:
https%3A%2F%2Fexample.invalid%2Fwatch%3Fepisode%3D7%26mode%3Dfull
The JavaScript component-encoding reference explains this operation. A local worksheet can compare the expected value with the encoded text without making a network call.
If the inner ampersand is emitted raw, a conventional outer query parser can interpret mode=full as a separate parameter. If the already encoded text is encoded again, %26 becomes %2526; one decoding step then leaves %26, rather than restoring the intended ampersand. Whether another encoding layer is required depends on a real additional embedding boundary.
Inspect three separate strings: the intended inner value, the emitted outer URI and the receiver's result after its documented parsing step. Also distinguish XML entity escaping from URI component encoding. A serialized XML representation and a URL parameter have different syntax; transforming both as though they were the same string can hide the actual defect.
5. Ask what the receiver actually used#
An HTTP success response shows that a request received a response at that boundary. It does not establish that the receiver associated every field with the intended campaign, accepted it as a reportable event or counted a viewable impression.
Where authorized receiver evidence exists, ask for the parsed value, validation result and relevant association. Compare these with the outbound representation from the same request. Keep “request observed,” “field parsed” and “event included in report” as separate checkpoints.
The missing-viewability diagnostic addresses whether the measurement event itself was supported and observable. Correcting a macro cannot manufacture a viewability observation that the integration never produced. The VAST error and timeout guide owns media and wrapper failures that require a different next step.
A hypothetical audit: preserve the unknown portion#
Imagine reviewing one required diagnostic field across 50 authorized test attempts. Classify each attempt once by the first demonstrated problem or its complete available path:
| Classification | Attempts |
|---|---|
| Emitted value and receiver-parsed value match the agreed contract | 32 |
| Placeholder survives into the emitted request | 6 |
| Value is substituted, but receiver parsing shows an encoding defect | 5 |
| Outgoing request is visible; receiver evidence is unavailable | 4 |
| No relevant outgoing request captured; ownership or capture remains unresolved | 3 |
These categories sum to 50. Observed complete-path agreement is 32 / 50, or 64%. Among the 43 attempts with enough evidence to reach the first three classifications, agreement is 32 / 43, approximately 74.4%.
The seven incomplete cases are not seven failed substitutions. They are an evidence queue. Neither percentage is an IVT rate, completion rate, paid-impression rate or estimate of website traffic. Define the selected field and test cohort before comparing a later audit; a different creative or substitution actor can change the population.
Repair one boundary, then retest the same contract#
A useful correction names the actor, supported field and demonstrated defect. Examples include fixing the documented macro spelling in the trafficked version, supplying an available permitted value at the responsible actor, or correcting one encoding boundary confirmed by receiver evidence.
Retest with a new authorized attempt and retain the earlier trace. Confirm that the deployed creative or template is the version you changed. Test the affected path and one relevant neighboring case, such as a permitted unknown value or a different wrapper route. Do not claim historical reports have been repaired because a new request is correct.
The anonymized streaming-publisher verification case concerns bounded measurement evidence, not universal access to player or server internals. For campaigns already measured through AdProof, request a scoped evidence review with the available campaign export, exact dates, timezone and relevant filters alongside the publisher's runtime trace. Keep unavailable substitution and receiver evidence explicit; an event export does not automatically expose every original VAST URL or private SDK field.
Frequently asked questions#
Can Chrome show a macro after replacement?
For a browser-owned request, inspect the actual Network entry and distinguish source from decoded parameter views. For a server-owned call, obtain server evidence. A template alone does not show the final runtime value.
Should every unknown macro become minus one?
No. Apply only the documented rules for that macro and context. Unknown, policy-withheld and inapplicable values can have different meanings. Arbitrary proprietary tokens do not acquire IAB semantics because they use brackets.
Does an encoded bracket mean replacement succeeded?
No. Encoding a placeholder changes its representation, not its meaning. Compare the template, emitted URI and receiver-parsed value to determine whether a real supported value was substituted.
Does HTTP success prove the event was counted?
No. Request response, field interpretation, report inclusion and the underlying measurement event require separate evidence. Preserve the unresolved boundary instead of treating HTTP success as a counting or viewability receipt.
Record the VAST substitution path.
Use the checklist to compare the template with the request made by the substituting system.
Use the tracking QA checklistOpens a practical guide. No email required.
