TroubleshootingCopy Anchor Link

Admin panel loads blank / shows a white pageCopy Anchor Link

JavaScript files are returning HTML instead of JavaScript. The Next.js standalone static files were not copied to the correct location.

Fix: Re-run the installer with the same config file.

bash install-stilmerce.sh -- --config=/tmp/stilmerce-install.env

All API requests return 502 Bad GatewayCopy Anchor Link

The API process is not running or crashed on startup.

sudo pm2 ls
sudo pm2 logs stilmerce-api --lines 50

Check that PostgreSQL and Redis are running:

systemctl is-active postgresql redis-server

If a migration failed, the logs will show the error. Fix the underlying issue, then restart:

sudo pm2 restart stilmerce-api

Storefront shows "Internal Server Error"Copy Anchor Link

The front service can't reach the API. Check the environment:

sudo pm2 logs stilmerce-front --lines 30

The most common cause is API_URL pointing to the wrong address in the standalone .env.production file. The correct path is:

/var/www/stilmerce/front/.next/standalone/.env.production

Verify API_URL=http://localhost:4000 (or whatever internal port your API is on), then restart:

sudo pm2 restart stilmerce-front

Images not loadingCopy Anchor Link

If product images return 404:

1. Check that the api/uploads directory exists and is readable by the process user
2. Check the Nginx config is proxying /uploads to the API correctly
3. If using Cloudinary, confirm USE_CLOUDINARY=true and all three Cloudinary env vars are set

Email not sendingCopy Anchor Link

Check SMTP settings and test connectivity from the server:

curl -v smtp://your-smtp-host:587

If the SMTP server requires TLS, make sure port 587 (STARTTLS) or 465 (SSL) is open and not blocked by a firewall.

Stilmerce does not crash or block registration/login when email fails — it logs the error and continues. Check pm2 logs stilmerce-api for MailerService errors.

SSL certificate not issuedCopy Anchor Link

Certbot requires:

• Port 80 open and reachable
• DNS A records resolving to your server IP (propagation can take up to 24h)

Check DNS:

getent ahostsv4 api.yourdomain.com

If DNS isn't ready, install with --skip-ssl first and add SSL later:

bash install-stilmerce.sh -- --config=/tmp/stilmerce-install.env

See Enabling SSL Later.

PM2 processes keep restartingCopy Anchor Link

Usually caused by the Node.js process running out of memory on a low-RAM server. Check:

sudo pm2 logs stilmerce-api --lines 100 | grep -i "heap\|memory\|killed"
free -h

Add a heap size limit to the PM2 startup:

sudo pm2 delete stilmerce-api
sudo pm2 start /var/www/stilmerce/api/dist/main.js \
  --name stilmerce-api \
  --node-args='--max-old-space-size=220'
sudo pm2 save

Adjust 220 (MB) based on your available RAM. A 2GB server running all three services needs roughly 200–220 MB per process.

Plugin install fails with "License required"Copy Anchor Link

In production, all plugins with requiresLicense: true in their manifest need a valid license key from stilgen.com.

Free plugins (those with "requiresLicense": false) never need a key and install without one — just enter your email in the store prompt.

Search returns no resultsCopy Anchor Link

Typesense may not be running or the index is empty.

systemctl is-active typesense-server
curl http://127.0.0.1:8108/health

If Typesense is running but results are empty, trigger a re-index from Admin → Settings → Search → Re-index.

LogsCopy Anchor Link