DocsDeveloper SectionTroubleshooting Guide and Common Errors

Troubleshooting & FAQ

A collection of common errors developers encounter during setup, API connection, and project deployment, along with their definitive solutions.

1. CORS Error in Inter-Service Requests

If you encounter the Access-Control-Allow-Origin error in the browser, check the values of the STORE_CORS and AUTH_CORS variables in .env:

.env

env

STORE_CORS=http://localhost:8000,https://store.yourdomain.com
ADMIN_CORS=http://localhost:9000,https://api.yourdomain.com
AUTH_CORS=http://localhost:8000,http://localhost:9000,https://store.yourdomain.com

2. Products Not Visible on Frontend (Publishable API Key)

Main Reason for Products Not Showing

After generating the Publishable Key in the Medusa panel (URL http://localhost:9000/app), you must click into the key and in the Sales Channels tab, connect it to the Default Sales Channel.

3. Color Swatches Not Rendering or Color Filter Issue

Ensure the title of the color option key in Medusa is strictly color or Color. To translate its name into different languages (English, Persian, Arabic, German, etc.), use Strapi so the reserved main key doesn't change.

4. Out of RAM and Server Crash During Docker Build

Use Phased Deployment commands, and if necessary, enable virtual memory Swap on Linux:

Create 4GB Swap memory on Ubuntu

bash

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

5. Adding New Block Styles in Production

You do not need to log into the VPS or run any terminal commands to add new styles. Simply go to Strapi Admin > Storefront Management, select the desired component style, and click Update Storefront. GitHub Actions will automatically pull the style from the registry, commit it to your repository, and deploy the new Storefront image to your server.

Automated Flow

bash

Strapi Admin (Storefront Management) -> GitHub Actions -> Build & Auto Deploy to VPS

6. Docker Permission Denied (unix:///var/run/docker.sock)

On a fresh VPS or Linux environment, docker commands may fail with permission denied. Add your Linux user to the docker group:

Fix Docker Permissions

bash

sudo groupadd docker 2>/dev/null || true
sudo usermod -aG docker $USER
newgrp docker
docker ps

7. Medusa Admin Login Loop or White Screen

Login Loop: Ensure MEDUSA_NODE_ENV=production. For plain HTTP IP setups (Profile A), set MEDUSA_ALLOW_HTTP_COOKIES=true in .env. For HTTPS (Profile B/C), keep it false.

White Screen: Never use MEDUSA_NODE_ENV=development in Docker Compose, as the admin UI is pre-compiled for production.

Medusa Environment Config

env

MEDUSA_NODE_ENV=production
MEDUSA_ALLOW_HTTP_COOKIES=false # or true for plain HTTP Profile A