Troubleshooting center

Fix your conversion, step by step

Search the exact message or symptom you see. Every entry lists the real cause recorded by the conversion engine and the fix that resolves it, including builder-specific issues.

17 solutions · 13 builder-specific sections

Upload

The upload fails or never reaches 100%

Symptom: The progress bar stalls, or you see “Uploading the results to our servers failed”.

Cause: The archive contains node_modules, .git history or large media, pushing it past the practical upload size.

  • →Delete node_modules and the .git folder before zipping
  • →Compress images over 2 MB, or move video files to an external host
  • →Zip the project folder itself, not a folder that contains several project versions
  • →Retry on a stable connection — the uploader retries automatically with exponential backoff
Upload

“No project root found” or the converter picks the wrong folder

Symptom: Conversion starts but reports a missing package.json or index.html.

Cause: The ZIP has an extra wrapper folder, or contains multiple projects side by side.

  • →Open the ZIP and confirm package.json or index.html sits at the first or second level
  • →Remove sibling folders such as backup/, old/ or design/
  • →For GitHub, use Code → Download ZIP so the structure matches the repository
Upload

The build stops because environment variables are missing

Symptom: Logs show “undefined env” or a runtime error while pre-rendering.

Cause: The project reads secrets at build time that only exist in your own hosting environment.

  • →Add a committed .env.example with placeholder values
  • →Guard secret usage with a fallback (for example `import.meta.env.VITE_X ?? ""`)
  • →Remove backend-only code paths from the public marketing pages before exporting
Build

The build fails on install

Symptom: The job stops early in the build stage with an npm/pnpm error.

Cause: A lockfile references a private package, or a dependency needs native compilation.

  • →Include the lockfile that matches your package manager (package-lock.json, pnpm-lock.yaml or yarn.lock)
  • →Remove private/registry-scoped packages that are not needed for the public site
  • →Pin the Node engine in package.json if your project needs a specific major version
Build

The build fails on TypeScript or lint errors

Symptom: “Type error” appears in the build log and the conversion is marked failed.

Cause: The project only ever ran in dev mode, where type errors are non-blocking.

  • →Run a production build locally once and fix the reported errors
  • →Or relax the strictest compiler flags for the export build
  • →Re-export after the local production build succeeds
Rendering

The preview shows an empty page

Symptom: The theme installs but the homepage is blank or shows only a header.

Cause: The app is a client-only SPA whose content is injected after hydration, and something blocked hydration during pre-render.

  • →Make sure the homepage renders meaningful markup without needing an API call
  • →Guard browser-only code with a mount check so it does not throw during pre-render
  • →Provide static fallback content for sections that stream data
Rendering

Only the homepage was converted

Symptom: The WordPress preview contains one page while your site has many.

Cause: Route discovery could not find the other routes: they are not linked and no sitemap or route manifest exists.

  • →Link every page from the header, footer or a sitemap page
  • →Ship a public/sitemap.xml with all routes
  • →Avoid routes that only exist behind a login or a client-side redirect
Rendering

The job stalls at a fixed percentage

Symptom: Progress freezes and the watchdog eventually marks the job as stalled.

Cause: A page never finishes loading — usually an endless animation, a polling request or a third-party widget.

  • →Remove chat widgets, analytics and A/B testing scripts before exporting
  • →Stop infinite polling loops on the marketing pages
  • →Retry the job — transient render failures are retried automatically up to three times
Images & assets

Images are missing after conversion

Symptom: Broken image icons or empty hero sections in the WordPress preview.

Cause: Images were served by a preview host, an optimizer endpoint or a CDN that requires the original domain.

  • →Store images inside the project (src/assets or public/) and import or reference them locally
  • →Avoid remote-only image URLs from your builder's preview environment
  • →If you use a framework image optimizer, allow unoptimized output for the export build
Images & assets

Fonts fall back to a system typeface

Symptom: Typography looks different in WordPress than on your original site.

Cause: Fonts were loaded from a private CDN or from a stylesheet that was not part of the export.

  • →Self-host font files inside the project and reference them from your CSS
  • →Keep the @font-face declarations in a stylesheet that is imported by the app
  • →Google Fonts links are preserved automatically when they are in the page head
WordPress

The theme will not activate

Symptom: WordPress reports a missing stylesheet or a PHP error on activation.

Cause: The ZIP was unzipped and re-zipped, which changed the folder structure WordPress expects.

  • →Upload the ZIP exactly as downloaded through Appearance → Themes → Add New → Upload Theme
  • →Do not unzip and re-zip on macOS — it adds __MACOSX wrappers
  • →Use PHP 8.1 or newer on your host
WordPress

Forms do not send email

Symptom: The form submits but nothing arrives in your inbox.

Cause: WordPress sends mail through PHP mail() by default, which most hosts block.

  • →Install Contact Form 7 or WPForms (the theme is prepared for both)
  • →Add an SMTP plugin and connect a real mailbox or transactional sender
  • →Send a test message from the plugin before going live
Payment & download

Can I look at the result before I pay?

Symptom: You want to check quality first.

Cause: Preview is intentionally free; only the deliverable ZIP is paid.

  • →Open the WordPress preview and click through every page
  • →Check pages, images, links and the mobile layout
  • →Pay €17 only when you are satisfied — you then download the theme immediately
Payment & download

The download button asks for payment again

Symptom: After paying you are shown the checkout once more.

Cause: The credit had not been registered yet when the page tried to download.

  • →Wait a few seconds and press the download button again — credits are confirmed by the payment webhook
  • →Make sure you are signed in with the account you used at checkout
  • →If it persists, open the dashboard: your paid conversion is listed there and stays downloadable
Payment & download

Will a page refresh charge me twice?

Symptom: You reload the download page.

Cause: Each conversion consumes exactly one credit, recorded server-side.

  • →No. Once a conversion is paid, the job is marked paid and re-downloads are free
  • →Every credit movement is logged and visible in your dashboard

Builder-specific problems

Lovable (React + Vite + Tailwind)

  • The conversion misses recent edits — Lovable syncs to GitHub asynchronously. Wait for the sync indicator to finish, then re-download the ZIP.
  • Images are missing in the preview — Move images from remote preview URLs into src/assets or public/ and re-export.
  • Only the homepage appears — Every route needs a link from the header or footer. Add a footer sitemap block so route discovery can find all pages.

Framer (Framer static export (HTML/CSS/JS))

  • Scroll animations behave differently — Framer's runtime drives complex scroll effects. Flatten them into CSS animations before exporting for the closest match.
  • CMS pages are missing — Draft CMS items are not exported. Publish every collection item you want in WordPress.
  • Fonts fall back to system fonts — Framer serves some fonts from its CDN. Upload custom fonts to the project so they are exported locally.

Bolt.new (Vite / React / Astro (varies per project))

  • The build fails on missing environment variables — Placeholder values are injected automatically, but committing a .env.example with the expected keys makes the build deterministic.
  • Only a blank shell renders — Bolt SPAs sometimes need a runtime render pass. The engine retries with a headless browser; make sure the app runs locally with npm run dev first.
  • Dependencies fail to install — Remove the lockfile mismatch by running npm install locally once and re-downloading the project.

Cursor AI (Any (React, Next.js, Vue, static))

  • Conversion detects the wrong framework — Keep the framework config file (vite.config, next.config, astro.config) in the ZIP root — detection relies on it.
  • The ZIP is too large — Exclude node_modules, .git and build caches. A source project is normally under 20 MB.
  • Monorepo confuses the builder — Zip only the web application package, not the whole workspace.

Claude (Artifacts & Projects) (React / static HTML)

  • Only one page is detected — Claude artifacts are often single-page. Split sections into separate HTML files or add real routes before exporting.
  • Tailwind classes have no styling — Artifacts rely on a Tailwind CDN script. Keep that script tag in index.html or add a real Tailwind build.
  • Images are placeholders — Replace placeholder URLs with local image files inside the project folder.

Google AI Studio (React / Vite / static)

  • The app needs an API key at runtime — Gemini API calls are runtime features. The converter renders the UI with placeholder values; dynamic AI responses are not part of a static theme.
  • Blank page after conversion — The app renders client-side only. The runtime render pass handles this automatically — check the render diagnostics if it still fails.
  • Missing styles — Ensure the CSS import is in the entry file rather than injected at runtime.

Replit (Node / React / static (varies))

  • The project contains a server — Only the frontend converts. Keep the client folder complete; Express/Flask backends are ignored.
  • Replit config files break detection — Leave .replit and replit.nix in place — they are ignored — but make sure the real framework config is present too.
  • Sliders or carousels do not move — Slider libraries are re-initialised by the UI polyfill layer. Use a standard library (Swiper, Keen, Glide) rather than a custom runtime.

Webflow (Webflow static export (HTML/CSS/JS))

  • CMS collection pages are missing — Webflow does not export CMS items. Convert the live URL instead so collection pages are crawled.
  • Interactions do not run — webflow.js must stay in the ZIP; it drives Webflow interactions inside WordPress too.
  • Forms do nothing — Webflow forms post to Webflow servers. They are re-mapped to Contact Form 7 during conversion.

Base44 (React application export)

  • Pages behind login are missing — Only public routes are converted. Move any content you need into public pages before exporting.
  • Data-driven lists are empty — Base44 entities load from its backend. Hard-code the content you want in the theme or rebuild it with a WordPress custom post type.
  • Blank render — The runtime render pass handles client-only apps; verify the app boots locally without backend errors first.

V0.dev (Next.js + React + Tailwind)

  • Build fails on server components — Server actions and route handlers are removed by the Next.js patch layer; keep pages presentational for the best result.
  • Images are broken — next/image optimised URLs are decoded to the original files automatically. Keep images in public/ so they can be resolved.
  • Dynamic routes are skipped — Add generateStaticParams or link the routes from navigation so they can be discovered.

React (Vite / CRA) (React SPA)

  • Routes render as 404 — Client-side routes must be linked from navigation or listed in a sitemap so route discovery finds them.
  • Blank page after build — Check the build runs locally with npm run build && npm run preview; the same build runs during conversion.
  • Assets 404 in the preview — Use relative asset imports rather than absolute paths tied to a custom base URL.

Next.js (Next.js App or Pages Router)

  • output: export fails — The patch layer applies static export automatically and removes API routes and middleware that block it.
  • Dynamic segments missing — Provide generateStaticParams or getStaticPaths so the routes can be pre-rendered.
  • Fonts flash or fall back — next/font files are copied locally; self-host fonts to avoid CDN dependencies.

Static HTML (HTML / CSS / JavaScript)

  • Only the homepage is converted — Every other HTML file must be linked from the navigation or present in the ZIP with a clean file name.
  • Styles missing — Use relative paths (css/style.css), not absolute paths tied to your old domain.
  • Header and footer duplicated — The engine detects repeated blocks by frequency; keep the markup identical across pages so it can be extracted into header.php and footer.php.

Related documentation

Conversion HubPrepare your websiteCompatibility matrixAfter conversionLive Site Editor pluginAll guidesPricingContact supportStart a free preview