Skip to main content
Every file in your extension is private to your extension until you say otherwise. A web page cannot load it, and neither can a content script that runs inside that page. The web_accessible_resources manifest key is the allowlist that opens specific files to specific origins. This page explains which callers need an entry, how the object form works, how globs and runtime URLs behave, and which console lines a missing entry prints.

Three ways a file gets read, and which one needs a declaration

From an extension page. A popup, an options page, a side panel, or a devtools page runs on the extension origin. It reads any file in the bundle, and no web_accessible_resources entry is involved. From a content script. The script’s own code is already running, but the assets that it pulls in are not covered by that. An img element, a fetch, a FontFace, or a dynamic import() that names a chrome-extension:// URL is a resource load, so the file must be listed. From the page’s own code. Anything in the page’s MAIN world, including a script that you injected with world: "MAIN", is web page code. It needs the file listed and it needs the page origin to fall inside matches. The rule to remember: the browser decides by who fetches the URL, not by who wrote the code.

Manifest snippet

Manifest V3 takes an array of objects. Each object pairs a list of resources with the matches patterns that are allowed to read them:
  • resources lists paths relative to the extension root. A relative path resolves from the folder that holds manifest.json.
  • matches limits which page origins may read those files. Keep it as narrow as the feature allows.
  • use_dynamic_url asks the browser for a URL that rotates per session, so a page cannot fingerprint your extension by a fixed id. Treat it as a Chromium field.
Globs are allowed in resources, and Extension.js keeps them as written. It does not expand fonts/*.woff2 into an explicit file list, so the emitted manifest carries the same pattern that your source carries. An explicit list is still the safer choice when you know the file names. Extension.js drops a Manifest V3 entry that has no resources array during normalization, because the browser cannot act on it.

Build the URL at runtime

Never write a chrome-extension:// URL by hand. Ask the runtime for it:
A root-absolute argument such as /images/logo.png is the stable form, and it is what Path resolution rewrites for you. The same call in a content script is the only correct way to reach the file, because a plain /images/logo.png in an injected stylesheet or element resolves against the host page instead. CSS works through that case for a web font. On Firefox the helper matters even more. Firefox gives each installation a random UUID in its moz-extension:// origin, so a URL that you copied from one profile is wrong in every other profile.

Per-browser differences

On Safari, enabling the extension is not enough. Until you grant website access, no content script runs on the page, so nothing asks for the resource in the first place. See Safari for the enable and grant steps. If your source is written against browser.* and you support a Chromium browser older than 148, or older than 152 with a devtools_page, pass --polyfill so the namespace exists there. Newer versions expose browser natively. See Cross-browser compatibility.

Console lines you will see

Copy the line that you see into search. Each one maps to one cause. Denying load of chrome-extension://<id>/images/logo.png. Resources must be listed in the web_accessible_resources manifest key. The file is not in any resources array, or the page that asked for it is outside matches. Add the path, then confirm that the pattern covers the page origin. GET chrome-extension://invalid/ net::ERR_FAILED The same denial seen from the network panel. Chromium rewrites a blocked extension URL to chrome-extension://invalid/, so the id disappears from the request. Fix the manifest entry, not the fetch. Security Error: Content at https://example.com/ may not load or link to moz-extension://<uuid>/images/logo.png. The Firefox form of the same problem. The add-on did not list the file, so the page is not allowed to link to it. Failed to load resource: net::ERR_FILE_NOT_FOUND The entry is correct and the file is missing from the output. Check dist/<browser>/ for the exact path that you declared. Uncaught ReferenceError: browser is not defined A browser.runtime.getURL call reached a Chromium browser older than 148 (152 with a devtools_page) with no polyfill. Build with --polyfill, or call chrome.runtime.getURL.

The Extension.js way

Extension.js merges what you declare with what the build discovers, then normalizes the result for each target:
  • Assets that a content script imports and content-script CSS output are added for you when the runtime needs the page to read them. Fonts follow their own rule, below.
  • From the release after 4.1.41, the files that an injected style sheet loads are added too. Chromium and Safari targets list every such file. Firefox targets list only fonts, because Firefox Manifest V3 blocks an injected sheet’s font without the entry and loads its images unlisted.
  • From the release after 4.1.41, Extension.js lists a font in web_accessible_resources only when a content script, a content script stylesheet or a stylesheet injected by file loads it. A font that only an extension page loads ships without an entry.
  • Paths are normalized for output. Extension.js removes a public/ prefix and a leading slash, so the entry names the file at the location where it lands.
  • Globs stay as written, and match patterns that carry a port or a port wildcard, such as http://localhost:3000/*, are accepted rather than rejected.
  • A group that you wrote with extension_ids and no matches keeps matches absent in the emitted manifest.
  • In development, Extension.js patches the entry set so reload and hot module replacement assets stay reachable. That patching is development only. See Reload and HMR.
  • From the release after 4.2.0, a listed stylesheet whose url() targets the build does not ship warns with W_WAR_INVALID and names each target. The stylesheet is copied as written, so the browser answers those files with a 404.
  • From the release after 4.2.0, dev warns with W_ASSET_MISSING as a build does when a listed public-root path, such as /foo.png, has no file. A copy that an earlier build left in the output folder no longer counts, and a listed file deleted during dev is removed from the output and warned about.

A page stays private until a script builds its URL

From the release after 4.1.39, the build adds an HTML page to web_accessible_resources only when a content script builds the page’s URL. Passing the path to runtime.getURL is the signal:
The build follows a literal path, a constant that holds the path, and a helper that passes its first argument to getURL. A URL that joins the extension origin or runtime.id with the path counts too. A script that only names the page does not expose it. A content script that sends the path to the background, which then opens the page in a tab, is the usual case. The page stays private, and the build prints one note per page:
A page that you list under web_accessible_resources yourself stays exposed, and the note does not print for it. Automatic merging is convenient, and it is not a review. Read the emitted dist/<browser>/manifest.json before a release and confirm that the exposed set is the set that you meant to expose:
  • Keep matches on the domains that actually need the file.
  • Prefer an explicit resource list over a broad glob.
  • Keep sensitive files out of the allowlist and serve them from an extension page instead.
  • Audit the list again after you add a content-script import, a font, or a new static asset.
Scaffold a project that loads an extension font into a page, which is the smallest complete example of this key:

See also