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:
- Newer apps (created from May 13, 2026) use TanStack Start.
package.jsonlists@tanstack/react-start, andvite.config.tsimports@lovable.dev/vite-tanstack-config. Part of the app runs as server code. - Older apps use React + Vite.
vite.config.tsimports fromvite, usually withlovable-tagger. The app runs in the browser, and server work happens in Edge Functions on the backend.
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:
package-lock.jsonis there: runnpm install.- Only
bun.lock(common in newer projects): runbun install, ornpm install, which creates apackage-lock.jsonfor you. Skipnpm cihere: it needs apackage-lock.jsonand stops without one.
"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:
- Sign-in. Login providers only send users back to addresses they know. Add your local address (
http://localhost:8080, or the port you use) to the redirect URLs where your sign-in provider is set up. If users land on the wrong address or an error page, see login redirects and "requested path is invalid". - Secrets you stored in Lovable (Stripe, Resend or OpenAI keys) never go into the repository. In older apps, the code that uses them runs in Edge Functions on your backend, so it still works from your computer. In newer apps, that server code runs on your machine, so it needs those values set there too.
- Lovable AI and app connectors use credentials that Lovable manages and that can't be copied out. In newer apps, those calls fail locally. Test them in the Lovable preview or in your published app.
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
- Work on your own branch and merge it into the branch Lovable syncs, usually
main. Don't force-push or rebase that branch: Lovable keeps its own copy, and rewriting the history replaces Lovable's work (the project owner can restore it from Project settings → Git). - Syncing doesn't deploy backend changes. A changed Edge Function or a new migration file does nothing until you ask Lovable in the project chat to deploy it, or run the SQL yourself.
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.