App Finishers

Fix guide · updated 2026-11-13

Lovable code won't run locally after export or GitHub sync

npm run dev fails · blank page on localhost · supabaseUrl is required · listen EAFNOSUPPORT :::8080 · bunx: not found

You downloaded your Lovable project, or cloned it from GitHub, and it won't start on your computer: npm install or npm run dev fails, or the page stays white. The code is usually fine. A Lovable project expects a few things that Lovable's servers provide, and your computer has to provide them instead. Here they are, in the order they usually break.

First: which kind of Lovable project is it?

Lovable builds two kinds of apps, and they run a little differently on your computer. Open package.json:

The steps below apply to both. Where they differ, the step says so.

Step 1: use Node.js 22

Lovable's own instructions for running and hosting a project outside Lovable use Node.js 22. Newer projects come with a recent Vite that refuses old Node versions. Check yours:

node -v

If it's lower than 22, install 22. With nvm:

nvm install 22
nvm use 22

Then delete the node_modules folder if a failed install left one, and install again.

Step 2: install with the lockfile your project has

Look at the files next to package.json:

"bunx: not found" when you start the app? Some projects call Bun inside their scripts, for example a "predev": "bunx tsx scripts/generate-sitemap.ts" line in package.json that runs before every npm run dev. Install Bun from bun.sh and run the command again.

Step 3: start it, then open the address it prints

npm run dev

Older projects don't use Vite's usual port 5173. Their vite.config.ts sets port: 8080, so the app is at http://localhost:8080. If 8080 is busy, Vite moves to the next free port. Newer projects get their port from Lovable's config. Either way, open the exact address the terminal prints after Local:.

Error: listen EAFNOSUPPORT: address family not supported :::8080: older projects also set host: "::", an IPv6 address. On a computer or container with IPv6 turned off, nothing can listen there. Start the app on a normal local address instead, without editing the file Lovable syncs:

npm run dev -- --host 127.0.0.1

Step 4: blank page or "supabaseUrl is required": the .env file

If the app starts but the page stays white, open the browser console (F12). supabaseUrl is required. means the app found no backend address. The Supabase client Lovable generates (src/integrations/supabase/client.ts) reads that address and its public key from the .env file at the project root:

VITE_SUPABASE_URL=https://xxxx.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=...
VITE_SUPABASE_PROJECT_ID=...

Lovable keeps .env in the repository on purpose, and its docs say never to add it to .gitignore. It goes missing when a template or a tool ignores it, or when the files were copied without hidden files (names that start with a dot). Copy .env from the code editor in Lovable to your local project, next to package.json. Then stop npm run dev and start it again: Vite reads .env only when it starts.

These VITE_ values are sent to the browser, which is fine for the URL and the publishable key. Never add a service role key or any other secret to them.

Step 5: it runs, but sign-in or some features fail

A clone gives you the code, not everything around it. Lovable's docs list what stays behind:

One warning before you click around: with the same .env, your local app reads and writes the same live database as your published app. Records you create or delete locally change real data, so test with test accounts.

If you change code locally

Still stuck?

Run the four checks in order: node -v shows 22, the install finished without errors, you opened the address the terminal printed, and .env sits next to package.json. Then read the first red line in the terminal or the browser console: it names the step that failed. Sources: Lovable's docs on hosting outside Lovable, Git sync and working locally and secrets, and the settings in public Lovable repositories (checked in November 2026).

Other Lovable app problems? See Fix a Lovable app.