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

8. HTTP 403 Forbidden during Translation Sync from Strapi

If clicking Sync Translations from Strapi yields an HTTP 403 Forbidden error, the Public role lacks permission to read storefront settings. Go to Settings > Users & Permissions > Roles > Public, enable the find permission for both Storefront-setting and Media Library, and save.

9. Search Input Frozen / Cannot Type in Header Search Modal

Cause: The storefront search bar uses React InstantSearch and queries Meilisearch directly from the client's browser. If the search.yourdomain.com subdomain has not been created in Cloudflare DNS, or if the browser fails to reach Meilisearch (due to DNS, SSL, or CORS errors), React InstantSearch's controlled input state freezes, preventing any typing in the input field.

Solution:
1. In the Cloudflare dashboard (under DNS > Records), add an A record for search pointing to your VPS IP address (DNS Only or Proxied with Full Strict SSL).
2. Verify that Meilisearch health endpoint is publicly accessible:
curl -I https://search.yourdomain.com/health
3. Ensure that NEXT_PUBLIC_MEILISEARCH_HOST and NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY were properly provided during the Storefront Docker build.

Check Meilisearch Health Endpoint

bash

curl -I https://search.yourdomain.com/health
# Expected response: HTTP/2 200 or HTTP/1.1 200 OK