Documentation

Troubleshooting

Organized by category. Each issue lists causes, the fix, and how to verify. When contacting support, include the diagnostics listed at the bottom — never secrets.

On this page

Installation & npm

“node is not recognized” / command not found

Causes: Node.js not installed or terminal opened before install. Fix: install Node 20+ LTS, close and reopen the terminal. Verify: node -v prints a version.

npm install fails with errors mid-way

Causes: Node too old; corrupted cache; antivirus locking files (Windows); network proxy.

rm -rf node_modules package-lock.json   # Windows: rmdir /s /q node_modules & del package-lock.json
npm cache clean --force
npm install

Verify: install completes with “added … packages”. If one specific package keeps failing, check its error line — native builds need build tools (macOS: xcode-select --install; Windows: VS Build Tools).

Environment & configuration

Changed .env but nothing changed

Cause: env vars load once at startup. Fix: stop the server (Ctrl+C) and start again. Verify: the startup banner shows in the terminal.

“Invalid environment variables” at build/start

Causes: missing required variable (commonly DATABASE_URL, APP_URL, or AUTH_SECRET); quotes/typos. Fix: compare your .env line-by-line with Environment Configuration. Verify: startup proceeds past validation.

Database & migrations

db:deploy hangs or times out

Causes: wrong password/host/port in DATABASE_URL or DIRECT_URL; pooled connection used for migrations (Supabase/Neon); firewall blocking 5432.

Fix: test the connection string in the provider's SQL editor or psql. DIRECT_URL must be the direct (non-pooled) string on pooled hosts. Verify: psql "YOUR_DATABASE_URL" -c "select 1;" returns 1.

“relation … does not exist” / missing tables

Cause: migrations not applied to this database (you may be pointing at a different DB than you think). Fix: confirm the database name in DATABASE_URL, run npm run db:deploy, then npm run db:seed if fresh. Verify: the tables list in your DB tool populates.

Login works but pages crash with Prisma errors

Cause: the Prisma client was generated from a different schema than the database (often after code updates). Fix:

npm run db:generate
npm run db:deploy
# restart the dev server

Login & authentication

“Credentials invalid” for the admin account

Causes: seeded with a different email/password than you think; password was set via HASH variant you no longer remember. Fix: set SEED_SUPER_ADMIN_* in .env and re-run npm run db:seed on a dev database — or use “Forgot password” if email works. Verify: login succeeds at /login.

Sessions drop immediately or “UntrustedHost” errors in production

Causes: AUTH_SECRET missing/different between restarts; accessing via a different host than APP_URL. Fix: set a strong fixed AUTH_SECRET; make APP_URL match the real public URL; restart. Verify: login persists across a page reload.

Application errors

Error page in the browser (red banner “Application error”)

Fix: read the terminal running the dev server — the real error prints there. Common ones: missing env var (above), DB connection (above), or a stale compiled state — stop and re-run npm run dev. If a dev server has been running through many code changes, a restart clears stale caches.

Page loads but looks unstyled

Cause: CSS didn't compile (usually only on first request). Fix: reload once; if it persists, stop, delete the .next folder, and run npm run dev again.

Images & uploads

Uploaded images 404 or disappear after redeploy

Cause: uploads live in the storage/ folder on disk; some platforms wipe it on redeploy. Fix: ensure the folder persists on your host; restore from backup; or use external image URLs (supported per product). Verify: an uploaded image URL opens.

“File too large” on upload

Cause: size limit. Fix: compress the image (most product photos are fine under 2 MB); server proxies need client_max_body_size raised (see deployment config).

Payments

Payment succeeds but order stays unpaid

Causes: webhook not configured or wrong signing secret; APP_URL mismatch. Fix: set the provider webhook to your HTTPS domain, paste its signing secret in Admin → Payments, restart if using .env. Check the provider dashboard's webhook deliveries for errors. Verify: a test payment flips the order to paid automatically.

Gateway option doesn't appear at checkout

Causes: provider disabled or missing credentials; gateway left in a mode whose credential slots are empty. Fix: Admin → Payments: enable, fill credentials for the active mode (TEST needs test keys, LIVE needs live keys). Verify: checkout lists the method.

Shipping

“Shipping is not available for: VENDOR …” at checkout

Causes: no zone matches the address (all zones scoped to countries the address isn't in); vendor shipping disabled; no active rates.

Fix: Admin → Shipping → Zones: add a fallback zone (e.g. “Rest of world”, country-agnostic) with a method+rate, or add the customer's country to an existing zone. Use the Shipping Calculator (Admin → Shipping) with that exact address to see the matched zone and diagnostics (missing weight, disabled method, etc.).

Verify: the calculator returns options, and checkout shows shipping for that address.

Weight-based method shows as unavailable

Cause: products missing weight data while the method requires it. Fix: set weight on products/variants (Admin → Products) or allow zero-weight fallback in the method config. Verify: the calculator no longer reports missing weight.

Email

No order/reset emails arrive

Causes: SMTP not configured; Gmail without app password; spam folder; missing SPF/DKIM.

Fix: configure SMTP (see Domain, SSL & Email), use an app password for Gmail, add provider DNS records. Verify: “Forgot password” delivers within a minute.

Production & domain

Site down after an update

Fix order: check pm2 status and pm2 logs salex --lines 50 for the error; if migrations changed, ensure npm run db:deploy ran; rebuild (npm run build) and pm2 restart salex. If all fails, restore the backup you made before updating.

502 Bad Gateway from Nginx

Cause: the app isn't running on port 3000. Fix: pm2 start npm --name salex -- start, then systemctl reload nginx. Verify: homepage returns 200.

Padlock missing / certificate errors

Fix: re-run certbot --nginx -d YOUR_DOMAIN.com; confirm the DNS A record points at this server.

Contacting support

If the steps above don't resolve it, contact the author via the Codecanyon support tab with:

  1. Your OS, Node version (node -v), and whether errors occur locally or on a server.
  2. The exact error text from the terminal (not a photo of a screen — copy-paste it).
  3. What you were doing when it happened, and which docs page/step you followed.
  4. Environment variable names you have set (never values).
Never share passwords, .env contents, API keys, private keys, or database dumps in support requests. No legitimate support agent needs them.