Blog

The X-Gtm-Server-Preview header, explained

Why your preview pane shows nothing, what the header actually does, and the three ways it gets lost.

Open the GTM debug console for a server container and you will see a long opaque string at the top labelled "tagging server preview header." That string is what tells your tagging server to record the request for inspection instead of processing it silently. Without it, your container behaves exactly as it does in production: it answers the request and forgets about it.

What the header looks like

X-Gtm-Server-Preview: ZW52LTV8b3VKMEpqV2t1ZkZDd0...

It is a base64 blob containing the workspace ID, the auth token, and an expiry. The container reads it on every incoming request and decides whether to log the request to the preview pane.

The three ways teams lose it

  1. The browser strips the header on cross-origin requests. If your client GTM lives on www.example.com and the tagging URL is data.example.com, you need CORS configured to expose this header explicitly.
  2. The header expires after one hour. The preview pane keeps refreshing it, but if you copy the value into a curl command and run that command twenty minutes later, you will get an empty pane and no error.
  3. Some CDNs strip non-standard headers from inbound requests by default. If you sit behind Cloudflare, Fastly, or similar, check the request rules before assuming the container is broken.

Test it from the command line

curl -X POST 'https://data.example.com/g/collect' \
  -H 'X-Gtm-Server-Preview: PASTE_FROM_DEBUG_PANE' \
  -d 'v=2&tid=G-XXXXXXX&en=test_event'

The event should show up in the preview pane within a couple of seconds. If it does not, the header is the first thing to verify. If the header is fresh and the request still does not register, your custom domain setup is the next place to look.