⚠ Vigencia por confirmar. Documento previo al estándar de documentación, migrado sin reescribir su contenido técnico. Revisar contra el código antes de usarlo como fuente de verdad.

Troubleshooting¶

Common issues and solutions.

Deployment Issues¶

❌ Workflow Build Fails¶

Error: "npm install timeout" or "npm ERR! code ENETUNREACH"

Causes & Solutions: 1. GitHub Actions npm cache stale → Rebuild forces fresh cache

# In GitHub Actions, can't force directly, but try:
git push origin staging --force  # Last resort, not recommended

Package-lock.json corrupted → Regenerate

rm package-lock.json
npm install
git add package-lock.json
git commit -m "chore: regenerate package-lock.json"
git push

Network issue in GitHub Actions → Usually resolves on retry; check GitHub status

❌ Health Check Fails (Auto-Rollback)¶

Error in logs: "Health check falló. Auto-rollback a imagen anterior..."

Likely causes: 1. Port 9000 blocked or not binding

docker ps | grep medusa_backend
docker logs medusa_backend | tail -50 | grep -i "listen\|port\|bind"

Database migrations failed
```
docker logs medusa_backend | grep -i "migration\|error"
```
Fix: Check .medusa/server package.json, verify database exists and credentials are correct
Dependency issue with new Medusa version
```
docker logs medusa_backend | grep -i "cannot find\|module not found"
```
Fix: Ensure package-lock.json is correct, rebuild

Container runs out of memory

docker stats medusa_backend
docker logs medusa_backend | grep -i "memory\|oom"

Fix: Increase Docker memory limit, optimize dependencies

Resolution: - Auto-rollback should have restored previous version automatically - Check logs to confirm: docker logs medusa_backend | grep "rollback" - If rollback also failed, manually deploy known-good tag (see Runbook)

Error: "unauthorized: authentication required" or "permission denied"

Cause: GHCR_PAT token is invalid or expired

Solution:

# Check if token exists in GitHub
# Settings → Developer settings → Personal access tokens

# Regenerate if expired:
# 1. Go to GitHub → Settings → Developer settings → Personal access tokens (classic)
# 2. Generate new token with scopes: read:packages, repo
# 3. Update repository secret GHCR_PAT
# Settings → Secrets and variables → Actions → GHCR_PAT

# Test manually (staging server):
echo "YOUR_PAT_HERE" | docker login ghcr.io -u YOUR_USERNAME --password-stdin

Runtime Issues¶

❌ Database Connection Error¶

Error in logs: "ECONNREFUSED 127.0.0.1:5432" or "password authentication failed"

Cause: PostgreSQL not running or credentials wrong

Solution:

# Check if postgres container is running
docker ps | grep postgres

# If not running, start it
docker compose up -d postgres

# Verify credentials match docker-compose.yml
docker compose exec postgres psql -U compulandia -d medusa-store -c "SELECT 1"

# If that works, restart medusa container
docker compose restart medusa

❌ Redis Connection Error¶

Error in logs: "Error: connect ECONNREFUSED 127.0.0.1:6379"

Cause: Redis not running

Solution:

# Check if redis container is running
docker ps | grep redis

# If not, start it
docker compose up -d redis

# Verify connection
docker compose exec redis redis-cli ping
# Should return: PONG

# Restart medusa
docker compose restart medusa

❌ Admin Dashboard Won't Load¶

Error: HTTP 500, blank page, or "Cannot GET /"

Likely cause: Build issue or missing admin files

Solution: 1. Check build completed:

docker exec medusa_backend ls -la .medusa/server
# Should show dist/, node_modules/, package.json

Check for build errors:

docker logs medusa_backend | grep -i "error\|failed" | head -20

Rebuild and redeploy:

git push origin staging  # Triggers rebuild

❌ Migrations Stuck or Failed¶

Error in logs: "Migration failed" or "Migration timeout"

Solution:

# Check which migrations are pending
docker exec medusa_backend npx medusa db:generate

# See migration status
docker logs medusa_backend | grep -i "migration" | tail -20

# If stuck, try rolling back specific migration (dangerous, use caution):
# Contact Medusa support or check their migration rollback docs

❌ Out of Disk Space¶

Error: "No space left on device"

Solution:

# Check disk usage
df -h

# Clean up Docker
docker system prune -a --volumes  # ⚠️ DELETES ALL UNUSED IMAGES/VOLUMES

# Or more conservative approach:
docker image prune -a  # Remove unused images only
docker container prune  # Remove stopped containers
docker volume prune    # Remove unused volumes

❌ Memory Usage Too High¶

Error: Container crashes, "Killed" or "OOM" in logs

Solution: 1. Increase Docker memory (on server)

# Edit docker-compose.yml, add to medusa service:
deploy:
  resources:
    limits:
      memory: 4G  # Increase from 2G

Optimize Node.js

# In docker-compose.yml environment:
NODE_OPTIONS: "--max-old-space-size=2048"

Restart to apply changes

docker compose down
docker compose up -d

Permission Issues¶

❌ "Permission denied" Running deploy.sh¶

Error: ./deploy.sh: Permission denied

Solution:

chmod +x /opt/medusa/deploy.sh
# Or in repo
chmod +x deploy.sh
git add deploy.sh
git commit -m "fix: ensure deploy.sh is executable"
git push

❌ Cannot Access Docker Socket¶

Error: "permission denied while trying to connect to Docker daemon"

Cause: User not in docker group on server

Solution:

# Add runner user to docker group
sudo usermod -aG docker _svc_actions_staging
# or for production
sudo usermod -aG docker _svc_actions_production

# Apply without reboot
newgrp docker

# Verify
docker ps

Version Issues¶

❌ "Cannot find module" After Upgrade¶

Error: "Cannot find module '@medusajs/framework/...'"

Cause: package-lock.json mismatch or incomplete install

Solution:

# Verify package-lock.json is tracked
git status package-lock.json

# Ensure full install
rm -rf node_modules
npm ci  # or npm install

# Rebuild
npm run build

# Commit and push
git add package-lock.json
git commit -m "chore: update dependencies for Medusa 2.15"
git push

Recovery Procedures¶

Full System Reset (Last Resort)¶

⚠️ Warning: Deletes all data. Use only if absolutely necessary.

cd /opt/medusa

# Stop everything
docker compose down -v  # -v removes volumes (DATA LOSS!)

# Restore database from backup
# See [Runbook - Restaurar backup](runbook.md#restaurar-desde-un-backup)

# Restart
docker compose up -d

# Verify
curl http://localhost:9000/health

Getting Help¶

Check logs first: docker logs medusa_backend | grep -i error
Review Runbook for common tasks
See Guía de despliegue del proyecto for architecture
GitHub Issues: https://github.com/CompulandiaTI/EcommerceV2Backend/issues
Medusa Docs: https://docs.medusajs.com

Troubleshooting¶

Deployment Issues¶

❌ Workflow Build Fails¶

❌ Health Check Fails (Auto-Rollback)¶

❌ Docker Login Fails¶

Runtime Issues¶

❌ Database Connection Error¶

❌ Redis Connection Error¶

❌ Admin Dashboard Won't Load¶

❌ Migrations Stuck or Failed¶

❌ Out of Disk Space¶

❌ Memory Usage Too High¶

Permission Issues¶

❌ "Permission denied" Running deploy.sh¶

❌ Cannot Access Docker Socket¶

Version Issues¶

❌ "Cannot find module" After Upgrade¶

Recovery Procedures¶

Full System Reset (Last Resort)¶

Getting Help¶