> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extensy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Extension Not Loading

> Step-by-step guide to diagnosing and fixing a Chrome extension that won't load.

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.

> [!NOTE]
>
> 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

> [!WARNING]
>
> 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.

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.