# Troubleshooting (https://docs.salla.dev/twilight/react/local-development/troubleshooting)



Find your symptom, check the cause, apply the fix.

## The page is blank at `localhost:5173` [#the-page-is-blank-at-localhost5173]

* **Cause:** bare `/` is a small shell, not the storefront.
* **Fix:** open `/en` or `/ar`.

## "Store is temporarily unavailable" [#store-is-temporarily-unavailable]

* **Cause:** the store in `.env` returned nothing. The id is wrong or the store is not public.
* **Fix:** run `salla theme dev --store` and pick another. To test one address only, add `?storeId=<numeric id>` ([Link a store](https://docs.salla.dev/twilight/react/local-development/link-a-store)).

## I changed the store and nothing changed [#i-changed-the-store-and-nothing-changed]

* **Cause:** Vite reads `.env` once, when it starts. Or the address still carries an old `?storeId=`, which wins over `.env`.
* **Fix:** restart the dev server and remove or update `?storeId=` in the address.

## A change I made in the dashboard does not show [#a-change-i-made-in-the-dashboard-does-not-show]

* **Cause:** the dev server reuses the store's settings for up to an hour, so it stays under the API's rate limit ([Link a store](https://docs.salla.dev/twilight/react/local-development/link-a-store#settings-are-reused-for-an-hour)). The local theme editor's side panel says when they were last fetched.
* **Fix:** press **Fetch fresh store data** at the bottom of the local theme editor's side panel.

## "Port 5173 is busy" [#port-5173-is-busy]

* **Cause:** another process uses the port. This is not an error.
* **Fix:** none needed. The CLI picks the next free port and prints it. Use `-p` to start from another one.

## `--port` is ignored [#--port-is-ignored]

* **Cause:** you passed it after `pnpm dev --`, and Vite drops it.
* **Fix:** run `salla theme dev --port 3000`.

## The dev server exits before it is ready [#the-dev-server-exits-before-it-is-ready]

* **Cause:** Vite failed to start, usually a syntax error in `vite.config.ts` or a broken import.
* **Fix:** run `pnpm dev` in the theme folder to see Vite's real error.

## The first load takes a long time [#the-first-load-takes-a-long-time]

* **Cause:** the first request compiles the server code. About ten seconds is normal.
* **Fix:** wait. After two minutes the CLI tells you to open the address yourself, because it may still be compiling.

## Dependencies fail to install [#dependencies-fail-to-install]

* **Cause:** a network problem, or a package manager other than pnpm 10 or newer.
* **Fix:** run `pnpm install` inside the theme folder. The folder is kept. npm and yarn are not supported.

## "Couldn't fetch the theme starter" [#couldnt-fetch-the-theme-starter]

* **Cause:** `create` could not download the starter package.
* **Fix:** check your network and npm registry settings, then run it again.

## "./my-store already exists" [#my-store-already-exists]

* **Cause:** the folder name derived from your theme name is taken.
* **Fix:** choose another name or remove the folder.

## "This folder isn't a Salla theme" [#this-folder-isnt-a-salla-theme]

* **Cause:** there is no `twilight.json` here.
* **Fix:** `cd` into the theme folder.

## "This folder is a Twig theme" [#this-folder-is-a-twig-theme]

* **Cause:** it is a legacy theme, and `salla theme dev` is for React themes.
* **Fix:** use `salla theme preview` there, or create a React theme.

## Node is too old [#node-is-too-old]

* **Cause:** Node older than 20.19.
* **Fix:** run `salla theme doctor` and follow what it prints ([Prerequisites](https://docs.salla.dev/twilight/react/local-development/prerequisites)).

## A fresh clone shows the demo store [#a-fresh-clone-shows-the-demo-store]

* **Cause:** `.env` is not in git.
* **Fix:** run `salla theme dev --store <id>` once.

## The theme editor does not open [#the-theme-editor-does-not-open]

* **Cause:** you are not signed in, the folder's git remote is not the theme's repository, or the theme is installed on none of your stores.
* **Fix:** run `salla login`, check that `salla theme list` shows the theme, and install it on one of your stores. The storefront still runs meanwhile ([Theme editor](https://docs.salla.dev/twilight/react/local-development/theme-editor)).

## `salla theme publish` stops at the checks [#salla-theme-publish-stops-at-the-checks]

* **Cause:** the folder has no `twilight.json`, your account is not linked to GitHub, or the git remote does not match the theme's repository.
* **Fix:** read the failing step the CLI prints. Link GitHub in the Partners portal, or point `origin` at the repository shown there ([Publish](https://docs.salla.dev/twilight/react/local-development/publish)).

## Still stuck [#still-stuck]

Read [How a theme works](https://docs.salla.dev/twilight/react/start/how-it-works) for the request flow.