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 installVerify: 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 serverLogin & 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.
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:
- Your OS, Node version (
node -v), and whether errors occur locally or on a server. - The exact error text from the terminal (not a photo of a screen — copy-paste it).
- What you were doing when it happened, and which docs page/step you followed.
- Environment variable names you have set (never values).