📘 Help & Documentation

Activate, update & troubleshoot

Everything you need to get the Lovable extension running — how to activate it, how to reload it after an update, how to hard-reload Lovable, and fixes for every common problem.

Step 1

Activate the extension

Activation unlocks native chat, frozen credits and unlimited prompts. You only do it once per device with your M00N-XXXX-XXXX-XXXX key.

  1. Install & load the extension for your browser (see step 2).
  2. Open the extension's side panel (click the Lovable toolbar icon).
  3. Paste your M00N-… key into the license field and press Activate.
  4. You'll see your plan badge (PRO) and a License expires in… countdown — you're ready.
🔑Keep your key private. It binds to your account and device on first use, so sharing it can lock you out. The countdown starts the moment you activate.
Step 2

Install for your browser

Packages are unpacked builds — always unzip first, then load the folder. Download your package →

Chrome · Edge · Brave · Chromium

  1. Unzip the package.
  2. Open chrome://extensions and turn on Developer mode.
  3. Click Load unpacked and select the unzipped folder.
  4. Open the side panel and activate.

Firefox

  1. Unzip firefox.zip.
  2. Open about:debugging → This Firefox.
  3. Load Temporary Add-on → pick manifest.json.
  4. Open the sidebar and activate.
↔️Firefox opens the sidebar on the left. To move it right: right-click the sidebar header → Move Sidebar to Right.

Android — Kiwi · Quetta · Lemur

  1. Download kiwi.zip and extract it (file manager) → a folder with manifest.json.
  2. Open your browser's Extensions page (Kiwi: kiwi://extensions; Quetta / Lemur: menu → Extensions), turn on Developer mode.
  3. Load unpacked → select the extracted folder, not the .zip.
  4. Tap the Lovable icon → the panel pops up → paste your key.
⚠️Works in Chromium-based Android browsers (Kiwi, Quetta, Lemur and similar). “Manifest missing or unreadable” means you picked the .zip instead of the extracted folder — extract first, then select the folder that directly contains manifest.json. Firefox-engine browsers can't load a Chrome zip.

Safari — macOS

  1. Unzip safari.zip.
  2. Run xcrun safari-web-extension-converter <folder>.
  3. Open the Xcode project, press Run, then enable it in Safari → Settings → Extensions.
  4. For local builds turn on Develop → Allow Unsigned Extensions, then activate with your key.

Safari — iPhone / iPad

  1. You still need a Mac + Xcode — iOS has no “load unpacked.”
  2. Run xcrun safari-web-extension-converter <folder> (it adds an iOS target).
  3. Plug in your iPhone, pick it as the run target, sign with an Apple ID, and press Run.
  4. On the phone: Settings → Safari → Extensions → enable Lovable and allow permissions. Trust the profile under Settings → General → VPN & Device Management.
⚠️A free Apple ID sideload expires after 7 days (re-install to renew); a paid Apple Developer account lasts a year. The extension is built for a desktop side panel, so the iPhone experience is limited.
Step 3

Update & reload the extension

This fixes most issues. After any new build, your browser keeps running the old copy until you reload the extension. If something looks wrong, do this first.

  1. Open chrome://extensions (Edge: edge://extensions, Brave: brave://extensions).
  2. Find Lovable and click the reload ⟳ icon.
  3. Downloaded a fresh package? Remove the old one, then Load unpacked the new folder.
  4. Then hard-reload Lovable (next step).
⚠️Firefox temporary add-ons unload when you restart the browser — reload from about:debugging if it disappears.
Step 4

Hard-reload Lovable

Lovable is a single-page app and caches heavily. A hard reload forces it to re-fetch fresh data and re-render — clearing stale chat text and UI.

Keyboard shortcut

Windows / Linux: Ctrl + Shift + R

macOS: Cmd + Shift + R

Full cache clear (if needed)

  1. Open DevTools (F12) and keep it open.
  2. Right-click the browser reload button.
  3. Choose Empty Cache and Hard Reload.
💡Rule of thumb after any update: reload the extension, then hard-reload Lovable. That resolves the large majority of problems.
Step 5

Troubleshooting — every common problem

Find your symptom below and follow the fix. The first four are Lovable's own security & billing checks (not a license problem) — each clears in under a minute.

+ “Additional verification is required” · captcha_required · 428

Lovable occasionally asks for human verification (a captcha). While the extension is active that captcha can't be shown, so prompts fail with captcha_required / status 428. Your license is fine.

  • Sign out of Lovable, then sign back in — a fresh session usually clears the verification. Retry your prompt.
  • Any popup mentioning captcha_required or status 428 means the same thing (the request_id changes each time).
+ “Workspace out of credits” · Payment required · 402

The extension needs at least 1 credit in your active Lovable workspace. Lovable gives every account 5 free credits per day, and those same credits work with the extension. At 0 credits, prompts fail with Payment required / status 402.

  • Wait for your daily free credits to refresh, or top up the workspace.
  • This often happens when the extension is used the wrong way and prompts silently consume credits — always send through the extension's flow, not Lovable's normal send.
+ “Project creation was blocked” · castle_denied · 403

Lovable's fraud protection flagged the request as suspicious — usually because of your IP. Your account is fine; apply any one fix:

  • Recommended: turn the extension off, create the new project from the Lovable dashboard as normal, then turn the extension back on.
  • Change your IP (different network / VPN) so Lovable sees a new address, then create the project.
  • Use a different workspace, or a new/secondary Lovable account, and create it there.
+ “Invalid token” · unauthorized · 401

The extension's session token expired or became invalid (unauthorized / status 401). This is the quickest to fix.

  • Open Lovable and reload the page in the same browser — a single reload restores a valid token. Then retry.
+ My messages show “Lovable” or the wrong text (e.g. “Fix errors”)Fixed

This came from how the extension routes chat through its proxy; Lovable would mis-render the message. The current build restores your real message text.

  • Reload the extension (step 3), then hard-reload Lovable (step 4).
  • New messages you send will show correctly.
  • Messages sent on a very old build can't be recovered (their real text was never captured) — send again if needed.
+ “Invalid or inactive license”

The key wasn't accepted or isn't active.

  • Re-check the key — it starts with M00N- and has no extra spaces.
  • Make sure it hasn't been revoked or already bound to another device.
  • Paste it again in the side panel and press Activate.
+ License expired / countdown ran out

The License expires in… bar counts down from when you activated. When it reaches zero the license is inactive.

  • Get a new coupon key and activate again.
  • The bar reflects the full period (activation → expiry) and updates live.
+ “Project creation was blocked due to suspicious activity” (castle_denied)

This 403 comes from Lovable's own anti-fraud system (Castle), not the extension. It happens when there's no fresh security token or Lovable flags the activity.

  • Open your Lovable project tab and interact with it once (this generates a fresh token), then retry New Project.
  • Hard-reload Lovable and try again.
  • If it persists, Lovable may be rate-limiting your account — it clears on their side, or contact Lovable support with the request_id in the error.
+ “No Lovable session token” / “Project not synced”

The extension needs an open Lovable project to act on.

  • Open a project at lovable.dev/projects/… in the active tab.
  • Wait for the side panel to show Synced! Project: …, then retry.
+ Firefox opened the extension full-screen instead of a sidebarFixed

The current Firefox build docks as a proper sidebar.

  • Reload / reinstall the latest firefox.zip.
  • To put it on the right: right-click the sidebar header → Move Sidebar to Right.
+ “Chat is disabled by admin” / a shortcut is greyed out

Some features are toggled from the admin panel. If a feature is disabled server-side, its button is hidden or shows this message. Contact your admin to enable it.

+ I changed / updated the extension but nothing changed

The browser runs the previously-loaded copy until you reload it.

  • Do step 3 (reload the extension) then step 4 (hard-reload Lovable).
  • If you re-downloaded a package, remove the old extension and Load unpacked the new folder.
+ The ZIP won't load

Packages are unpacked builds — you must unzip first, then load the resulting folder. Loading the .zip itself won't work.

Still stuck?

Nine out of ten issues are solved by reloading the extension and hard-reloading Lovable. If you've done both and it still persists, please contact your reseller for support.

📩 Contact your reseller for support