Skip to content

Fix "chrome.userScripts is undefined" in a Chrome extension

6 min readModerok team

Why chrome.userScripts is undefined in Manifest V3, the permission and Allow User Scripts toggle that fix it, and what still breaks after.

If chrome.userScripts is undefined in your Manifest V3 extension, two separate gates are involved and the manifest is only the first one. Declare the permission and the hosts:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "minimum_chrome_version": "120",
  "permissions": ["userScripts"],
  "host_permissions": ["*://example.com/*"]
}

Then the person running your extension has to switch it on. On Chrome 138 and later that is a per-extension Allow User Scripts toggle on the extension's details page at chrome://extensions/?id=YOUR_EXTENSION_ID. Before 138 it was the global Developer mode toggle. Until that switch is on the API is unusable, and on 138 and later the namespace is not even defined.

Why chrome.userScripts is undefined when the permission is set

Chrome's User Scripts API reference tells you to "add the "userScripts" permission to your manifest.json and "host_permissions" for sites you want to run scripts on", then adds the part that surprises people: "After your extension receives the permission to use the userScripts API, users must enable a specific toggle". It also warns that "The specific toggle required, and the API's behavior when disabled, vary by Chrome version."

The reference is blunt about why a second gate exists. Unlike content scripts and the scripting API, "the User Scripts API lets you run arbitrary code", code "provided by the user that cannot be shipped as part of your extension package." The permission gets you to the gate; the user opens it.

Chrome 138 changed the failure mode

If the answers you find do not match your symptom, the failure mode changed under you. Chrome's post Enabling chrome.userScripts in Chrome Extensions is changing (29 May 2025) says "we are transitioning from the global Developer Mode toggle to a new per-extension Allow User Scripts toggle."

Before Chrome 138, touching the namespace with developer mode off was itself an exception: "This threw an error if developer mode was disabled." From 138 on, "the API is undefined if unavailable." So a cold start with the toggle off now gives you TypeError: Cannot read properties of undefined (reading 'register'). Throwing did not disappear in 138 though, as the next sections show.

Two details decide how often you hit this:

  • "All new extensions installed after the migration will default to the Allow User Scripts toggle being set to off."
  • "On the first launch of 138 and newer a one-time migration will automatically enable the new toggle" for existing extensions granted the userScripts permission, and only "if the Developer Mode toggle is enabled." Users who never enabled developer mode were not migrated into a working state.

The availability check that works on every Chrome version

Do not feature-detect by reading the property. On pre-138 Chrome the read itself threw, and on current Chrome a stale context can hand you a namespace that is present but unusable. Chrome's check calls a method for that reason: "This check attempts to call a browser.userScripts() method that should always succeed when the API is available." The reference recommends it "as it works in all Chrome versions":

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Call it before every registration path, and use the result to show a setup screen naming the toggle. Chrome documents no API that opens it and no prompt you can trigger.

What still breaks after the toggle is on

A context that is already running does not pick up the change. The reference covers both directions in one note. Enabling: the undefined state "only resets when an extension script context reloads", so a user who flips the toggle on while your worker is alive still sees undefined there. Revoking: "if a user revokes access while your service worker is running, browser.userScripts remains defined. However, in this scenario, attempting to call any of its methods throws an error." That is why a typeof guard is not enough. A worker recovers either way, being torn down on idle and re-evaluated on the next wake (see why your service worker keeps stopping). A long-lived options page does not, so re-run the check there.

Your registrations are wiped by your own updates. "User scripts are cleared when an extension updates." The documented recovery is to "add them back by running code in the runtime.onInstalled event handler in the extension service worker", and the same paragraph narrows which firing to act on: "Respond only to the "update" reason passed to the event callback." onInstalled also fires for install, chrome_update and shared_module_update. Add the listener during the worker's initial synchronous evaluation or a revived worker misses it.

chrome.runtime.onInstalled.addListener(async (details) => {
  if (details.reason !== "update") return;
  if (!isUserScriptsAvailable()) return;
  await chrome.userScripts.register([
    {
      id: "highlight",
      matches: ["*://example.com/*"],
      js: [{ file: "user-script.js" }],
    },
  ]);
});

The script object has required fields and one reserved character. matches and js must both be present for register(), and js "must be a non-empty array". The id rule is easy to trip with a generated key: it "must not start with a '_' as it's reserved as a prefix for generated script IDs."

Messaging does not use the handlers you know. "Before sending a message, you must call configureWorld() with the messaging argument set to true", and messages arrive elsewhere: "they're received using dedicated event handlers (meaning, they don't use onMessage or onConnect)", namely runtime.onUserScriptMessage and runtime.onUserScriptConnect.

The world is not your content-script world. world defaults to USER_SCRIPT, "the execution environment that is specific to user scripts and is exempt from the page's CSP". That exemption is not what distinguishes it, since an isolated content-script world is not governed by the page's CSP either (content scripts: "When a content script is injected into the main world, the CSP of the page applies."). The real difference is that this world's policy is yours to change: configureWorld() takes a csp property whose "default is the ISOLATED world csp", the policy that for content scripts "prevents the use of eval() as well as loading external scripts".

Host access is still a separate grant. userScripts is an API permission; the match patterns in host_permissions are what let a script land on a page, as covered in host_permissions vs permissions in Manifest V3.

Firefox differences

Firefox has this API. The permission model is what will not port. MDN's userScripts page: "In Firefox, userScripts is an optional-only permission declared in the optional_permissions manifest key. Your extension must check that the permission has been granted by checking the availability of the userScripts API namespace or using permissions.contains() and, if not, request it using permissions.request()."

So the Chrome manifest above is wrong for Firefox twice over: the string belongs under optional_permissions, and you must request it at runtime from a user gesture. The request also has a shape rule, from MDN's optional_permissions page: "Optional-only permissions must be requested individually and alone through the permissions.request() API." Do not bundle userScripts with anything else. The prompt is also not the only gate: "Users can manage optional permissions from the Firefox Add-ons Manager."

The MV3 API arrived in Firefox 136: "A new version of the userScripts API is available on desktop Firefox. This version of the API is for use in Manifest V3 extensions and provides broad compatibility with Chrome, although permissions mechanisms differ across the browsers." Note the older Firefox API of the same name is a different thing: MDN keeps the Manifest V2 shape on a separate userScripts (legacy) page, so legacy code does not carry over.

Finding out how many of your users are blocked

A blocked install looks identical to a working one from your side: no error reaches you, the user just sees an extension that does nothing. The only way to size it is to report the check. Send two event names rather than one event carrying a boolean, because custom events are counted per event name rather than broken down by property:

Moderok.track(isUserScriptsAvailable() ? "user_scripts_ok" : "user_scripts_blocked");

Watching those two counts after an update tells you whether your setup instructions are landing. The custom events guide covers naming and the flat property rules.