Test tubes in a metal rack, one containing clear green liquid.

Troubleshooting Chrome's origin trials

Origin trials are a way to test a new or experimental web platform feature. This guide explains how to troubleshoot common problems with trial tokens in meta tags, headers, and scripts. You'll also learn about debugging support in Chrome DevTools.

Published on Updated on

This guide assumes a working knowledge of origin trials in Chrome.

If you encounter a bug with origin trials in Chrome, please submit a new issue on the Chrome origin trials GitHub repo.

Checklist

To troubleshoot an origin trial, work through each of the issues below using the supplied links.

Try it out!

The demos below show each of the ways to provide an origin trial token and access a trial feature:

Use Chrome DevTools to check tokens

From Chrome 93 DevTools provides origin trial information in the Application panel for the selected frame.

Chrome DevTools  origin trials information in the Application panel

Expand the top frame to inspect origin trial tokens available for a subframe. For example, for the demo page at ot-iframe.glitch.me, you can see that the page in the iframe provides a token.

Chrome DevTools    Application panel, showing origin trial tokens for page in iframe
  • Token Status: Whether the page has a valid token. Note that for some origin trials there may be other factors, such as geographical restrictions, that mean the origin trial feature is not available, despite the presence of a valid token.
  • Origin: The Web Origin registered for the token.
  • Expiry Time: the maximum (latest) possible expiry date/time for the token, which will normally match the end of the trial. This is not the same as the Valid Until date for the token displayed on your origin trial's My Registrations](https://developer.chrome.com/origintrials/#/trials/my) page, which shows how long the token is currently valid for, and can be extended.
  • Usage Restriction: Usage limits, which can be set for some trials.
  • Third Party: Whether third-party matching is enabled for the token. This is available for some origin trials, where a trial feature needs to be accessed on multiple sites from third-party scripts.
  • Match Sub-Domains: Whether subdomain matching is enabled for the token. This enables an origin trial feature to be tested on multiple subdomains of an origin, without requiring a different token for every subdomain.

Chrome DevTools will display a warning next to the trial name if the trial is not available in your region, the token has expired, or if there are other restrictions.

Chrome DevTools  origin trials information in the Application panel showing expired token
Gotchas

If a page provides an origin trial dynamically via script, it may not be shown initially in the Application panel. You may need to reload Chrome DevTools (not the page).

For examples of pages that do include an origin trial token, see the demos listed above.


It's not working! 🤔

If your origin trial isn't working as expected, make sure you've met the following conditions.

You're testing in Chrome, not Chromium or another browser

Chrome origin trials are designed to work for Chrome users. Don't rely on Chrome origin trial tokens to enable trial features in other browsers, including Chromium, and other Chromium-based browsers. This is because Chrome origin trials are specific to features made available in Chrome for experimentation.

Caution

As described below, some origin trials are not rolled out to all Chrome channels.

Additionally, not all origin trial features can be made available on all platforms or operating systems. Some origin trials may only be available on desktop, Android, or WebView.

In particular, Chrome on iOS and iPadOS does not support Chrome origin trials. All browsers on iOS and iPadOS must use WebKit, the same engine used by Safari. Chrome on iOS and iPadOS is built on WKWebView.

Microsoft Edge has its own origin trial framework. Enrollment in an Edge origin trial won't enable a feature in Chrome.

The origin trial is enabled for the Chrome versions accessing your site

Access to trials is limited to specific versions of Chrome. In some cases, this may mean a trial feature is only available to pre-Stable Chrome channels: Canary, Dev and Beta.

You can check version availability from the registration page for the trial:

Chrome Origin Trials page for First Party Sets & SameParty with Chrome availability highlighted

You can check the Chrome version you're using from chrome://version.

The origin trial is not disabled by Chrome settings

If an individual user reports that a feature is not working for them, check that the feature is not disabled in their Chrome settings. For example, Privacy Sandbox features can be disabled from the chrome://settings/privacySandbox page.

Keywords and syntax are correct

Make sure to use appropriate keywords and syntax for origin trial tokens.

Caution

These examples truncate the token value. Make sure to check the whole token—or at least the start and end of it! It's easy to accidentally leave out a character.

A complete token looks like this:

Bj3DysCv1VjknU4jJvkDEwnQZK/vmse1rcd5jZogunrkwtKW92
vmygya6gyKe5GveTObBy3NT5DiC8yiiXnXGwMAAABZeyJvcmlnaW9i7
iJodHXwczovL3NpbXBsLmluZm86NDQzIiwiZmVhdHVyZSI6Ik5BIiwi
ZXhwaXH5IjoxNjMxNjYzOTk5LCJpc1N1YmRvbWFpbiI6dHJ1ZX0=

For first-party usage, a token can be provided in an origin-trial meta tag:

    <meta http-equiv="origin-trial" content="Aj4DysCv3VjknU3...">

Alternatively, a token can be provided in an Origin-Trial response header. Here's an example using Express in Node.js:

app.use(function(req, res, next) {
res.setHeader('Origin-Trial', 'Aj4DysCv3VjknU3...')
next();
});

Tokens can also be provided using JavaScript:

function addTrialToken(tokenContents) {
const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = tokenContents;
document.head.appendChild(tokenElement);
}
Caution

For first-party usage, tokens can be provided via in an origin-trial meta tag, an Origin-Trial response header, or via JavaScript.

Third-party tokens must be provided via JavaScript.

First-party token origin matches page origin

Make sure the Web Origin value selected when you register for a trial matches the origin of the page that has the meta tag or header which provides the token.

For example, if you selected https://example.com as the Web Origin:

Chrome Origin Trials  page showing https://example.com selected as Web Origin

You might get a token value like this:

Chrome Origin Trials  page showing token value.

Check that this value matches the token used on the page you're troubleshooting.

For a token provided in a meta tag, check the HTML:

    <meta http-equiv="origin-trial" content="Aj4DysCv3VjknU3...">

For a token provided in a header, you can check the token value from the Chrome DevTools Network panel under Response Headers:

Chrome DevTools  Network panel showing origin trials response header

First-party token is served from the origin that uses it

To enable access to an origin trial feature for code included in a page served from your origin, provide a trial token in a meta tag, header, or via JavaScript from the same origin.

The origin registered for a token must match the origin that serves it.

The Third-party matching option is only provided for origin trials where it makes sense to try out a feature in a third-party context. Not every origin trial offers third-party tokens.

Third-party token origin matches script origin

You can register to participate in an origin trial for scripts that are injected on other origins. For example, if you want scripts that are served from javascript-library.example to take part in an origin trial, you need to register a token with third-party matching for javascript-library.example.

Chrome origin trials  registration page showing third-party matching selected

The origin value for a third-party token must match the origin of the script that injects it.

Third-party script uses a third-party token

You cannot enable a third-party script to participate in an origin trial on your site simply by registering a token for your origin, and not for the script.

Third-party scripts need to use tokens with third-party matching enabled, injected via the script itself (not included in a meta tag or header on your site) using code like the following:

function addTrialToken(tokenContents) {
const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = tokenContents;
document.head.appendChild(tokenElement);
}

Origin trial feature access is supported for the method used to provide a trial token

Some types of access to origin trial features require you to provide a trial token in a specific way. For example, the only way to enable origin trial access for service workers and shared workers is to provide a token in an Origin-Trial header.

Subdomain matching is enabled for a token used on a subdomain

If an origin trial feature doesn't seem to be working for some pages on your site, check that tokens are correctly set up for the subdomains serving them.

When you register for an origin trial, you can optionally choose to match all subdomains of the origin:

Chrome origin trials  registration page showing subdomain-matching selected

You can also match subdomains for third-party tokens:

Chrome origin trials  registration page showing third-party matching and subdomain-matching selected

Subdomain tokens will not be issued for origins in the Public Suffix List. For example, you cannot register an origin such as https://appspot.com or https://github.io, though you can register for domains within that origin, such as https://example.appspot.com or https://example.github.io.

The token is still valid

Tokens are valid for six weeks after they're created. Beyond that, you must submit feedback in order to extend the Valid Until date. Origin Trials Guide for Web Developers explains how to make sure your token is valid for an entire origin trial.

There is always a gap after the end of the final origin trial for a feature, and when the feature begins to be rolled out to all Chrome users: usually two weeks. In other words, there will always be a time during which a feature is not available in origin trial and hasn't yet been made available by default to all users.

Running an origin trial has more detail about trial timelines.

You can check for active tokens on your Chrome Origin Trials My Registrations page:

Chrome origin trials  My Registrations page showing Valid Until date

Chrome DevTools displays Status Success if the token is still valid:

Chrome DevTools  origin trials information in the Application panel, highlighting Status: Success

If your token has expired, DevTools will display Status Expired and your My Registrations page for the trial will display an Expired Tokens section:

Chrome origin trials  My Registrations page showing expired tokens

The origin trial hasn't ended

You can check the end date for an origin trial from its registration page:

Chrome Origin Trials page for First Party Sets & SameParty with Trial Available details highlighted

For trials that have ended, DevTools will display something like this:

Chrome DevTools  origin trials information in the Application panel showing ValidTokenNotProvided and Status Expired

You will be sent automated emails when feedback is required or a token is about to expire, though not when the trial ends.

Caution

There may be more than one origin trial for a feature.

Some features may undergo multiple origin trials before being rolled out in Chrome to all users.

Check the blink-dev mailing list for updates on the status of the feature you're testing.

The origin trial is available in your region

Not all origin trials are supported in all geographical regions.

If a trial isn't supported in your region, Chrome DevTools will display a TrialNotAllowed warning:

Chrome DevTools  origin trials information in the Application panel showing TrialNotAllowed warning

Origin trial usage restrictions haven't been exceeded

By default, an origin trial feature will be enabled on any page that has a valid token for the trial.

However, except in rare cases, origin trial usage is limited to a maximum of 0.5% of all Chrome page loads. The origin trial feature will be disabled if total usage by all Chrome users exceeds that amount. DevTools will show the token status as disabled.

★ The Expected Usage field on the trial registration page doesn't impact your origin trial token. It's purely informational for Chrome's origin trial team.

Some trials also provide an option to limit usage, which means origin trial features will be disabled for some users. This option is made available from the registration page for an origin trial that offers it:

Chrome origin trials  registration page showing usage restrictions

If you're noticing that access by your users to an origin trial feature is lower than expected, make sure that 'Standard Limit' is selected.

Gotchas

Access to trials is limited to specific versions of Chrome. In some cases, this may mean a trial feature is only available to pre-Stable Chrome channels: Canary, Dev and Beta.

Check that the origin trial is enabled for the Chrome versions accessing your site.

Iframes provide their own tokens

To enable an origin trial feature, an iframe must provide a token valid for its origin. Iframes don't inherit access to features enabled for pages that contain them.

A demo showing access to an origin trial feature in an iframe is available at ot-iframe.glitch.me.

Permissions policies are correctly configured

Some origin trial features may be affected by a Permissions-Policy header (previously known as a Feature-Policy header). You can check for this in the Intent to Experiment for the trial feature, or in developer documentation for the feature on web.dev or developer.chrome.com/blog.

Make sure the feature you are attempting to access is not blocked by a Permissions-Policy directive. You can check for response headers in the Chrome DevTools Network panel, and view the full list of allowed features in the Application panel.

Chrome DevTools    Application panel, showing Permissions Policy Allowed Feature

What about the workers?

Origin trials features can be made available to service workers, shared workers, and dedicated workers. However, the only way to enable access for service workers and shared workers is to provide a token in an Origin-Trial header. Dedicated workers inherit access to features enabled by their parent document.

Find out more


Photo by Bill Oxford on Unsplash.

Last updated: Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.