Fix Local Extension Manifest Import Errors

A local extension import can fail before the confirmation screen when MaskPilot cannot identify one valid extension root or cannot validate its manifest.json. This is separate from a store extension failing to download during profile launch, so clearing store installation files will not repair it.

Match the message to the package

Symptom	What to check
The source format is not supported	Select the extension’s root folder or a ZIP package. Local import does not accept CRX packages.
The manifest cannot be found	For a folder, manifest.json must be directly inside the selected folder. A ZIP may place it at the package root or inside one detected wrapper folder.
Multiple local extensions are found	The ZIP contains more than one folder that looks like an extension root. Split them into separate packages and import one at a time.
The ZIP cannot be opened	Download or build the package again from the trusted source. Do not bypass package checks or copy files from an unrelated release.
The manifest is invalid or unsupported	Confirm that the file is valid JSON, uses manifest_version: 3, and contains a valid name and version.
The minimum browser version is invalid	Use a valid browser version value supplied by the extension developer. Do not remove the requirement merely to make the import pass.

MaskPilot also validates declared browser capabilities and website access entries. If the message points to one of these declarations, compare it with the extension developer’s original Manifest V3 package rather than inventing a replacement permission or domain pattern.

Check the folder or ZIP structure

For a folder import, select the directory that directly contains manifest.json, not its parent repository or downloads folder.

For a ZIP import, use one of these layouts:

extension.zip
├── manifest.json
├── background.js
└── icons/

or:

extension.zip
└── extension-release/
    ├── manifest.json
    ├── background.js
    └── icons/

Do not put several extension releases or several folders containing their own manifests into one ZIP. Remove operating-system shortcuts and symbolic links from a package; rebuild it from regular files supplied by the trusted source.

Validate the manifest without weakening it

1. Open manifest.json in a text editor and confirm it is JSON, not a JavaScript file. JSON comments and trailing commas are invalid.
2. Confirm that manifest_version is the number 3.
3. Confirm that name is present and resolves to readable text. A localized name also requires the corresponding localization files.
4. Confirm that version uses a browser-extension version format rather than a label such as latest or beta.
5. If minimum_chrome_version is present, keep the developer’s valid version requirement and later select a compatible profile browser version.
6. Restore permission and website-access declarations from the original trusted package if they were edited or damaged.

The official Manifest format reference likewise requires manifest.json at the extension root and identifies Manifest V3, name, and version as core fields. The extension debugging guide shows that an invalid required field prevents the manifest from loading.

Retry from a clean package

1. Keep the failed package unchanged as evidence if its origin or integrity is uncertain.
2. Obtain a fresh folder or ZIP from the same trusted developer or rebuild the documented release output.
3. Import that package again and review the name, version, required browser version, website access, and browser capabilities on the confirmation screen.
4. Choose a narrow application scope and test the extension in a disposable profile before wider use.

See import a local browser extension for the normal import and device-only boundaries. If import succeeds but the profile later reports a browser-version conflict, use the extension compatibility checklist instead.

What MaskPilot does not verify at import

Passing the import check does not prove that third-party code is safe or that every referenced script, icon, and website workflow will run correctly. It verifies the package and manifest information needed for local management. Import only content whose source and purpose you trust, then test its behavior without exposing production credentials.

Before contacting support, record the source type, package name, whether manifest.json is at the selected root, the visible error, and the target profile’s browser version. Remove source code, credentials, tokens, private domains, and unrelated business data unless support explicitly needs a minimal redacted sample.