> ## 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.

# Common Errors

> Fixes for the most common errors when generating or loading a Chrome extension built with Extensy.

Most Chrome extension errors come down to manifest configuration, file paths, or timing issues. Use the list below to identify your error and apply the fix.

> [!NOTE]
>
> If your extension loads but doesn't behave as expected, right-click the popup and select **Inspect** to open the DevTools console. Chrome will show you the exact line of code that's failing.

> **Generation timeout**
>
> **Cause:** Your prompt describes a very complex extension, or the Extensy generation service is under high load.
>
> **Fix:** Simplify your prompt and break the extension into smaller features. Generate the core functionality first, then add features through refinement prompts. If the timeout persists across multiple attempts, reach out on the [Extensy Discord](https://discord.gg/HB6DZYws) for assistance.

> **Manifest file is missing or unreadable**
>
> **Cause:** You selected the wrong folder when clicking **Load unpacked**, or the ZIP was not fully extracted.
>
> **Fix:** Select the unzipped folder that directly contains `manifest.json`. If your unzipped folder contains another subfolder, open that inner folder and load it instead.

> **Permission errors in manifest**
>
> **Cause:** Your `manifest.json` requests permissions using Manifest V2 syntax, or includes permissions that are restricted under Manifest V3.
>
> **Fix:** Ensure all permissions use valid MV3 names (for example, use `"scripting"` instead of `"tabs"` for content script injection where possible). Remove any permissions your extension does not actively use.
>
> ```json theme={null}
> {
>   "manifest_version": 3,
>   "permissions": ["storage", "activeTab", "scripting"]
> }
> ```

> **Content Security Policy (CSP) violation**
>
> **Cause:** Manifest V3 prohibits inline scripts (JavaScript inside `<script>` tags in HTML) and the use of `eval()`.
>
> **Fix:** Move all JavaScript into separate `.js` files and reference them with `<script src="popup.js"></script>`. Remove any `eval()` calls from your code.
>
> ```html theme={null}
> <!-- Correct: external script reference -->
> <script src="popup.js"></script>
>
> <!-- Incorrect: inline script (blocked by MV3 CSP) -->
> <script>document.getElementById('btn').onclick = () => {};</script>
> ```

> **Extension fails to load after unzipping**
>
> **Cause:** The ZIP was extracted into a nested folder structure, or `manifest.json` references files that are missing from the directory.
>
> **Fix:** After unzipping, confirm the folder structure matches what `manifest.json` expects. Every file referenced in the manifest (background script, popup, icons) must exist at the exact path listed.

> **Could not load background script**
>
> **Cause:** The path to your service worker in `manifest.json` does not match the actual filename on disk.
>
> **Fix:** Confirm the `service_worker` value in your manifest matches the exact filename in your extension folder, including case.
>
> ```json theme={null}
> "background": {
>   "service_worker": "background.js"
> }
> ```

> **Extension context invalidated**
>
> **Cause:** You reloaded the extension in `chrome://extensions`, but the old content script is still running in an open tab.
>
> **Fix:** Refresh the webpage you're testing. This restarts the content script with your updated extension code.

> **Popup not appearing**
>
> **Cause:** The `action` key in your manifest is missing `default_popup`, or the path points to a file that doesn't exist.
>
> **Fix:** Add the correct popup path to your manifest and confirm the file exists in your extension folder.
>
> ```json theme={null}
> "action": {
>   "default_popup": "popup.html",
>   "default_icon": "icons/icon48.png"
> }
> ```

> **Unchecked runtime.lastError**
>
> **Cause:** An asynchronous Chrome API call (such as `chrome.tabs.sendMessage`) failed without an error handler.
>
> **Fix:** Add a `chrome.runtime.lastError` check in your callback, or wrap the call in a `try/catch` block.
>
> ```javascript theme={null}
> chrome.tabs.sendMessage(tabId, { action: "ping" }, (response) => {
>   if (chrome.runtime.lastError) {
>     console.error(chrome.runtime.lastError.message);
>     return;
>   }
>   console.log("Response:", response);
> });
> ```

> **net::ERR\_BLOCKED\_BY\_CLIENT**
>
> **Cause:** Another extension (such as an ad blocker) is conflicting with your extension or blocking its network requests.
>
> **Fix:** Disable other extensions temporarily, or test your extension in an Incognito window where other tools are turned off by default.

> [!TIP]
>
> If you can't resolve an error manually, paste the full error message into Extensy as a refinement prompt: "I'm seeing this error in Chrome — can you fix my extension code?" Extensy will attempt to identify and patch the issue.


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