DocumentaciónGuía para DesarrolladoresPreguntas Frecuentes y Solución de Problemas

Guía de Resolución de Problemas (Troubleshooting)

Respuestas directas y soluciones prácticas a las preguntas más frecuentes durante el desarrollo y el despliegue en servidor.

1. Los Cambios Guardados en Strapi No Aparecen en la Tienda

Comprueba los webhooks en Strapi y asegúrate de que el valor x-strapi-secret coincide con REVALIDATE_SECRET en tu archivo .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. Error de Conexión con Medusa o Productos No Visibles

Verificación de Publishable API Key

Verifica que la clave pública esté configurada en .env y que el Canal de Ventas (Sales Channel) esté asignado a los productos en Medusa Admin.

3. Problemas con Certificados SSL Automáticos en Caddy

Asegúrate de que el registro DNS tipo A de tu dominio apunte a la IP de tu VPS y que los puertos 80 y 443 estén abiertos en el firewall.

4. Error de Conexión Rechazada en PostgreSQL o Redis

Comprueba que todos los contenedores pertenezcan a la misma red de Docker y que haya suficiente espacio en disco en el servidor.

Comandos de Comprobación de Salud de Contenedores

bash

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

5. Inspección de Registros Centralizados y Diagnóstico

Accede al panel de Portainer CE o utiliza el comando docker compose logs -f para diagnosticar errores en vivo.

Monitoreo de Logs en Tiempo Real

bash

docker compose logs -f storefront
docker compose logs -f medusa
docker compose logs -f strapi

6. Recompilar un Solo Contenedor sin Detener los Demás

Cuando actualices el código del frontend o backend, puedes reconstruir únicamente el servicio necesario:

Comando para Recompilar un Solo Contenedor

bash

docker compose up -d --build storefront

7. Reiniciar la Base de Datos y Cargar Datos de Muestra

Para restablecer el catálogo de prueba en el entorno de desarrollo:

Comando para Sembrar Datos de Prueba

env

docker compose exec medusa yarn seed

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. Campo de búsqueda bloqueado / No se puede escribir en el modal de búsqueda

Causa: La barra de búsqueda utiliza React InstantSearch y consulta a Meilisearch directamente desde el navegador del cliente. Si el subdominio search.yourdomain.com no está creado en Cloudflare DNS o el navegador no puede conectarse (por errores de DNS, SSL o CORS), el estado del input se bloquea y no permite escribir.

Solución:
1. En el panel de Cloudflare (DNS > Records), añade un registro tipo A para search apuntando a la IP de tu VPS.
2. Verifica el estado de Meilisearch:
curl -I https://search.yourdomain.com/health
3. Asegúrate de haber configurado NEXT_PUBLIC_MEILISEARCH_HOST y NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY durante la construcción de la imagen de Storefront.

Verificar estado de Meilisearch

bash

curl -I https://search.yourdomain.com/health
# Respuesta esperada: HTTP 200 OK