Troubleshooting

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

The page is blank at localhost:5173Copy Anchor Link

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

"Store is temporarily unavailable"Copy Anchor Link

• 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).

I changed the store and nothing changedCopy Anchor Link

• 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.

"Port 5173 is busy"Copy Anchor Link

• 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 ignoredCopy Anchor Link

• 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 readyCopy Anchor Link

• 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 timeCopy Anchor Link

• 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 installCopy Anchor Link

• 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"Copy Anchor Link

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

"./my-store already exists"Copy Anchor Link

• 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"Copy Anchor Link

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

"This folder is a Twig theme"Copy Anchor Link

• 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 oldCopy Anchor Link

• Cause: Node older than 20.19.
• Fix: run salla theme doctor and follow what it prints (Prerequisites).

A fresh clone shows the demo storeCopy Anchor Link

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

The theme editor does not openCopy Anchor Link

• 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).

salla theme publish stops at the checksCopy Anchor Link

• 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).

Still stuckCopy Anchor Link

Read How a theme works for the request flow.