VASTlint
Validate

VAST error codes / Wrapper errors

VAST error 301: Wrapper timeout / URI unreachable

Short answer: A wrapper's VASTAdTagURI timed out or could not be loaded.

Inspect the wrapper chain first

VAST error 301 is a wrapper-chain failure. Inspect each hop, then test the resolved tag.

Validate this XML →Test the resolved tag →Inspect this wrapper chain →

What your player reported

301 · Timeout of VAST URI provided in Wrapper element, or of VAST URI provided in a subsequent Wrapper element. (URI was either unavailable or reached a timeout as defined by the media player.)

Wording from the IAB VAST 4.3 specification error table. Players may shorten or reformat it, but the code is the same.

What it means

The player requested the VASTAdTagURI and the next VAST document did not arrive before the player's own timeout. That timeout is the player's setting, not an attribute in the tag. 303 means the next document arrived and had no ad. 302 means the player stopped because the chain was too deep. 301 means this request did not finish.

The request for the next VAST document did not finish

301 means the player asked for a VASTAdTagURI and did not get a document back before its own timeout. The timeout is not an attribute in the tag and it is not a number in the VAST specification. Each player picks one. A chain that is fast enough for one player can 301 on another with a shorter budget, on the same URI.

The URI that timed out can be the first wrapper or a wrapper further down. The spec text covers both. The Error URL on the wrapper that was waiting is the one that receives [ERRORCODE] substituted as 301. Wrappers closer to the start of the chain may also record it if they were still waiting on the same fetch.

How to tell 301 from 302 and 303

303 means the next document arrived and contained no ad: an empty VAST, a no-fill, or an Ad with nothing to play. The network call succeeded. 302 means the player stopped because it had followed more wrappers than it allows, and it never required the next host to be down. 301 means this particular fetch did not complete. If the inspector shows a response body, you are not looking at 301, whatever the vendor dashboard says.

304 is later: an InLine was in hand and did not display in time. 402 is later still: a MediaFile URL timed out. A 301 never chose a media file, because the player did not yet have the InLine that lists them. Debugging 301 inside the CDN that hosts the mp4 wastes the time. The failed host is the ad server in VASTAdTagURI.

What you should see on the wire

Open the chain in the inspector and find the hop with no document: a timeout, a DNS failure, a connection reset, or an HTTP URI the app refused. An empty VASTAdTagURI never leaves the device, and some players still report 301 because there was nothing to wait for. Give the hop a reachable HTTPS URI. If every hop returns XML and the last body is an empty VAST element, change the diagnosis to 303.

A wrapper that returns HTML, a parking page, or a 200 with an empty body is not a VAST document. Players disagree on whether that is 301 or a general wrapper error, 300. The practical test is the same: the hop did not produce VAST. Replace the URI.

Common causes

  • The VASTAdTagURI host did not answer, or answered too slowly for that player
  • A redirect to a dead host, or a host the player cannot resolve
  • An HTTP URI on a page or app that blocks mixed content
  • An empty VASTAdTagURI, which has no request to wait for

How to fix it

Open the wrapper in the inspector and read the status of the hop that never returned a document. Give that hop a reachable HTTPS VASTAdTagURI. If every hop returns XML and the last one is empty, the code you wanted was 303, not 301.

The XML the player was holding

This is the shape that produces error 301. The player then calls the Error URL with [ERRORCODE] set to 301.

<Wrapper>
  <VASTAdTagURI><![CDATA[https://ad.example.com/vast?id=123]]></VASTAdTagURI>
  <Error><![CDATA[https://ad.example.com/error?code=[ERRORCODE]]]></Error>
</Wrapper>

VAST XML fragment only. This excerpt belongs inside a complete VAST document, so standalone validation will fail until it is wrapped in a full <VAST>response.

VAST error codes are runtime buckets emitted by the player. They tell you where the failure happened, not which line of XML caused it. Paste the raw tag into the validator to map this code onto the exact element and rule.

Related vastlint rules

Related error codes

Debug this tag now

Validate the XML, follow the wrapper chain, or check it in CI before launch:

# CLI: exits non-zero on errors, ideal for pipelines
vastlint check creative.xml

Further reading