Manifest V3 "background.service_worker" required / not found in CI

By Daniel Zoghalchali·Latchkey

A Manifest V3 background must reference a service_worker script that exists in the package. A missing key or a path that the bundler did not emit fails validation or load.

What this error means

Validation reports that the background service worker file could not be found, or the manifest has a background block with no service_worker.

MANIFEST_FIELD_REQUIRED
"/background" is missing required "service_worker".
No such file or directory: "background.js" referenced by background.service_worker

Common causes

service_worker path not in the build output

The manifest points at background.js, but the bundler emitted a hashed or differently-named file, so the referenced path is missing.

Background block without a service_worker key

A V3 manifest declares background but omits the required service_worker.

How to fix it

Reference the emitted service worker file

1. Confirm the exact filename the bundler writes for the background entry.
2. Set background.service_worker to that path.
3. Verify the file is present in the packaged zip.

"background": {
  "service_worker": "service-worker.js",
  "type": "module"
}

Check the worker is in the package

List the built output and confirm the service worker file exists before packaging.

- run: test -f dist/service-worker.js

How to prevent it

• Keep manifest paths in sync with bundler output names.
• Assert the service worker file exists before packaging.
• Avoid content-hashed names for the background entry, or template the path.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation