Skip to main content
If your extension isn’t appearing in Chrome after you’ve downloaded the ZIP from Extensy, work through the checklist below. Most loading failures are caused by one of a small number of common issues.

​
Loading checklist

1

Enable Developer mode

Open chrome://extensions in a new tab. In the top-right corner, confirm the Developer mode toggle is turned on. Without it, the Load unpacked button won’t appear.
2

Select the unzipped folder, not the ZIP

When you click Load unpacked, navigate to the folder you extracted from the Extensy ZIP — not the ZIP file itself. Chrome cannot load a compressed archive directly. If you haven’t extracted the ZIP yet, do that first.
3

Confirm manifest.json is present

Open the folder you’re trying to load. Verify that manifest.json is directly inside it — not inside a subfolder. If your extraction created a nested folder (e.g., extension/extension/manifest.json), load the inner folder.
4

Check for errors on the extension card

After loading, if the extension card shows an Errors button in red, click it. Chrome provides a line-by-line description of what failed. This is the fastest way to pinpoint the problem.
5

Validate manifest.json for syntax errors

A single missing comma or mismatched brace in manifest.json will prevent the extension from loading entirely. Open the file and check for:
  • Missing commas between properties
  • Mismatched { } or [ ] brackets
  • Keys using Manifest V2 syntax (such as browser_action) instead of V3 equivalents
You can paste the contents of manifest.json into a JSON validator to catch syntax errors quickly.
6

Verify permissions are valid for Manifest V3

If your manifest requests permissions that don’t exist in MV3, the extension will fail to load. Check that every entry in your permissions array is a valid MV3 permission. Replace any deprecated V2 keys as needed.
7

Pin the extension icon to the toolbar

If the extension loads without errors but you can’t find its icon, it may be hidden. Click the puzzle piece icon in the Chrome toolbar and click the pin icon next to your extension name to make it visible.
8

Reload and refresh after every change

Chrome does not hot-reload extensions. After modifying any file, click the reload icon (↺) on the extension card in chrome://extensions, then refresh the tab you’re testing on. Both steps are required.
Chrome will not automatically pick up file changes. Every edit you make requires a manual reload of the extension card and a page refresh on any tab where the content script runs.

​
Reading extension logs

If the extension loads but doesn’t do what you expect, use the browser’s developer tools to find out why.
  • Popup logs — Right-click the extension popup and select Inspect to open the DevTools console for popup.js.
  • Background script logs — On chrome://extensions, click the service worker link on your extension card to inspect background activity.
  • Content script logs — Press F12 on the page where your content script should be running to see its output.

​
Common causes of “Failed to load extension”

  • Broken JSON — A missing comma or mismatched bracket in manifest.json
  • Missing files — Your manifest references a file (such as icon.png or background.js) that isn’t in the folder
  • Reserved or deprecated keys — Using MV2-only keys like browser_action in an MV3 manifest
Ad blockers and security extensions can interfere with your extension’s scripts. If you’ve ruled out all other causes, try loading and testing your extension in an Incognito window with all other extensions disabled.
If you’re stuck, try creating a minimal manifest.json with only the required fields and add files back one at a time until the failure reappears. This isolates exactly which file or configuration is causing the problem.