Solución de problemas

Docker no se está ejecutando

failed to connect to the docker API at unix:///…/docker.sock; check if the path is correct and if the daemon is running

Las versiones antiguas de Docker muestran "Cannot connect to the Docker daemon" en su lugar. En ambos casos, el motor de Docker no está iniciado.

1. 01

   Abre Docker Desktop

   Inicia Docker Desktop y espera a que indique que el motor está en ejecución. En Linux, inicia el servicio: sudo systemctl start docker.
2. 02

   Comprueba que Docker responde

   TerminalCopiar

   docker info

   Resultado esperado: Muestra una sección Server en lugar de un error.
3. 03

   Vuelve a ejecutar tu comando de inicio

   docker compose up --build para Full Stack, o tu docker build y docker run para el paquete Admin Dashboard.

Un puerto ya está en uso

ports are not available: exposing port TCP 0.0.0.0:3030 … bind: address already in use
Bind for 0.0.0.0:3030 failed: port is already allocated
Error: listen EADDRINUSE: address already in use :::3030

Las dos primeras líneas vienen de Docker, la última de yarn dev o yarn start. Otro programa ya escucha en 3030 o 8000: a menudo una ejecución anterior del panel, o el servidor de desarrollo de otro proyecto.

1. 01

   Averigua qué ocupa el puerto

   En macOS o Linux, con el puerto del mensaje:

   TerminalCopiar

   lsof -i :3030

   En Windows, en PowerShell:

   TerminalCopiar

   netstat -ano | findstr :3030
2. 02

   Detenlo

   Cierra ese programa o detén la ejecución anterior: Ctrl+C en su terminal, docker compose down en su carpeta, o docker stop para un contenedor que iniciaste con docker run. Luego inicia el panel de nuevo.
3. 03

   O ejecuta el panel en otros puertos

   Con Full Stack en Docker, crea un archivo llamado .env en la carpeta dashboard-2-full-stack, junto a docker-compose.yml, con el puerto que necesites. DASHBOARD_PORT mueve el panel y API_PORT la API; las direcciones que usan las aplicaciones, CORS_ORIGIN incluido, las siguen por sí solas.

   dashboard-2-full-stack/.envCopiar

   DASHBOARD_PORT=3040

   Luego ejecuta de nuevo el mismo comando. Un inicio fallido continúa donde se detuvo:

   Terminalen dashboard-2-full-stackCopiar

   docker compose up --build

   Resultado esperado: El panel responde en su nuevo puerto, aquí localhost:3040Local.

• Paquete Admin Dashboard en Docker: cambia el número de la izquierda de -p, por ejemplo docker run -p 3040:3030 dashboard-2, y abre localhost:3040Local. La aplicación dentro del contenedor siempre escucha en 3030.
• Sin Docker: define PORT=3040 en el .env del panel (crea el archivo con solo esa línea si no tienes uno), o ejecuta PORT=3040 yarn dev en macOS y Linux. Con una API, añade también la nueva dirección al CORS_ORIGIN y al FRONTEND_URL de la API.
• La API sin Docker: cambia PORT en back-end/.env, y NEXT_PUBLIC_API_BASE_URL y NEXT_PUBLIC_WEBSOCKET_BASE_URL en el .env del panel, a la vez.

La construcción de Docker falla

La primera construcción descarga las imágenes base, todas las dependencias y la fuente árabe del panel desde Google Fonts, y luego construye las imágenes. Se detiene con "failed to solve" y el paso que falló cuando algo se interpone.

• Sin conexión o tiempo de espera agotado: la construcción necesita acceso a internet. Vuelve a ejecutar el comando cuando tengas conexión; los pasos terminados quedan en caché.
• No space left on device: libera espacio en Docker Desktop o revisa cuánto usa Docker con docker system df.
• Falla siempre en el mismo paso: vuelve a construir sin la caché y luego inicia.

docker compose build --no-cache
docker compose up

Para el paquete Admin Dashboard, añade --no-cache a tu comando docker build.

Un primer inicio que parece atascado suele estar todavía cargando los datos de ejemplo. El panel arranca solo cuando la API indica que está sana, lo que puede tardar hasta un minuto.

Yarn dice que su versión es 1.22

This project's package.json defines "packageManager": "yarn@4.8.1…". However the current global version of Yarn is 1.22…

Cada aplicación fija Yarn 4 a través de Corepack. Este mensaje significa que Corepack aún no está habilitado, así que respondió en su lugar el Yarn global antiguo.

corepack enable

Luego ejecuta yarn install de nuevo. Si tu Node.js no tiene Corepack (Node.js 25 y posteriores), instálalo primero con npm install -g corepack.

El panel no arranca con un Node.js más antiguo

node: bad option: --env-file-if-exists=.env

yarn dev y yarn start del panel leen .env con una opción que Node.js añadió en la versión 22.9. Comprueba la tuya:

node -v

Si muestra una versión inferior a 22.9, instala Node.js 22.9 o posterior, ejecuta corepack enable de nuevo, elimina la carpeta node_modules de la aplicación y ejecuta yarn install otra vez. Con Docker nada de esto se aplica: las imágenes traen su propio Node.js.

La API se detiene antes de iniciarse

The API cannot start: JWT_SECRET is not set. Set it in back-end/.env to the output of: …
The API cannot start: JWT_SECRET is still the example value from .env.example, so anyone can sign a token for any account. …
The API cannot start: CORS_ORIGIN is not set. List the dashboard origin (comma separated if there are several), …

La API revisa sus ajustes antes de iniciarse y muestra una línea por cada problema. Las causas:

• No hay archivo `.env`, o `JWT_SECRET` está vacío. Crea el archivo en back-end con cp .env.example .env.
• `JWT_SECRET` sigue siendo el valor de ejemplo con `NODE_ENV=production`. Cualquiera podría firmar un token con el ejemplo público, así que un inicio en producción lo rechaza. Genera tu propio secreto.
• `CORS_ORIGIN` está vacío con `NODE_ENV=production`. Defínelo con la dirección del panel.

Genera un secreto con:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

Con Docker no necesitas uno: un contenedor sin un JWT_SECRET propio, o con el de ejemplo, genera un secreto y lo guarda en el volumen de datos.

• Ajustes de la API

El inicio de sesión falla

• Comprueba la cuenta. El Super Admin es admin@example.com con Admin@123; los demás administradores de ejemplo usan admin123.
• "That email and password combination didn't work. Please try again." responde tanto a una contraseña incorrecta como a un correo desconocido, y también a una base de datos sin cuentas. Sin Docker, ejecuta yarn seed en back-end: yarn dev crea las tablas por sí solo, pero solo el seed añade las cuentas.
• "Too many failed sign-in attempts. Wait 15 minutes, then try again." Una dirección falló RATE_LIMIT_LOGIN inicios de sesión (10 por defecto) en 15 minutos. Espera, o reinicia la API: el recuento se guarda en su memoria.
• La página de inicio de sesión nunca responde. El panel no puede llegar a la API: consulta el siguiente problema.
• Cambiaste la contraseña del Super Admin y ya no la tienes: empieza de nuevo con datos de ejemplo limpios, más abajo.

El inicio de sesión falla

• En la API simulada, inicia sesión con admin@example.com y Admin@123, o con un Viewer de ejemplo como john.smith@admin.com con admin123. Estas cuentas viven en tu navegador: una contraseña que cambiaste allí sigue cambiada hasta que borres los datos del sitio.
• En tu propia API, la cuenta tiene que existir allí. En la API de esta plantilla, el seed añade las mismas cuentas. Si ninguna cuenta funciona, puede que el panel no llegue a la API: consulta el siguiente problema.

Las páginas se quedan vacías y el navegador informa de CORS

Access to XMLHttpRequest at 'http://localhost:8000/api/auth/login' from origin 'http://localhost:3040' has been blocked by CORS policy

La consola del navegador muestra esta línea cuando el panel funciona en una dirección que la API no acepta. La API responde a los navegadores solo desde las direcciones de CORS_ORIGIN, que por defecto es http://localhost:3030.

CORS_ORIGIN=http://localhost:3040
FRONTEND_URL=http://localhost:3040

• Escribe cada dirección exactamente como la muestra el navegador, con el esquema y el puerto y sin barra final, separadas por comas si hay varias. Luego reinicia la API.
• FRONTEND_URL es la única dirección que aceptan las actualizaciones de permisos en vivo. Muévela junto con el panel.
• Con Full Stack en Docker no editas estos valores: los definen DASHBOARD_PORT y DASHBOARD_URL en el .env junto a docker-compose.yml.
• Un panel que no puede llegar a la API en absoluto, porque está detenida o en otra dirección, falla del mismo modo pero sin la línea de CORS. Comprueba que localhost:8000/api/healthLocal responde y que el NEXT_PUBLIC_API_BASE_URL del panel nombra esa API.

El panel muestra datos de ejemplo en lugar de mi API

Sample data
No API is connected (NEXT_PUBLIC_API_BASE_URL is empty), so the dashboard runs on built-in sample data. …

El panel se construyó sin una dirección de API, así que funciona con su API simulada integrada. Eso ocurre sin archivo .env, con NEXT_PUBLIC_API_BASE_URL= vacío, o con una imagen de Docker construida sin el --build-arg.

• Sin Docker: cp .env.example .env en la carpeta del panel, revisa NEXT_PUBLIC_API_BASE_URL y reinicia yarn dev, o ejecuta yarn build de nuevo para una compilación de producción.
• Docker, paquete Admin Dashboard: vuelve a construir la imagen con --build-arg NEXT_PUBLIC_API_BASE_URL=…, como en la guía de instalación.
• Docker Compose: el archivo compose siempre construye el panel con la dirección de la API, así que este aviso no aparece allí.

• La API simulada integrada

Un cambio en el .env del panel no tiene efecto

Cada valor NEXT_PUBLIC_* se compila en el JavaScript que carga el navegador cuando se construye la aplicación. Cambiar el archivo no cambia nada hasta que la aplicación se vuelve a construir.

Un cambio de rol llega al panel solo después de recargar

Cuando cambian los permisos de un rol, la API avisa por WebSocket al panel de cada administrador con sesión iniciada, y los menús y botones se ajustan sin recargar. El panel se conecta a NEXT_PUBLIC_WEBSOCKET_BASE_URL, la dirección de la API sin /api, y la API acepta la conexión solo desde FRONTEND_URL, la dirección del propio panel.

• Define ambos con el lugar donde las aplicaciones se ejecutan de verdad, luego reinicia la API y reconstruye el panel.
• Un FRONTEND_URL sin definir acepta solo http://localhost:3030.
• El panel también vuelve a leer los permisos en cada página que abre, así que nada queda desactualizado mucho tiempo.

El asistente de IA pide una clave de API

The server has no key for this model's provider. Add your own API key to keep going.

La API no tiene clave para el proveedor del modelo que elegiste. Pega tu propia clave en el diálogo, que se queda en tu navegador, o añade la clave del proveedor a back-end/.env y reinicia la API (con Docker Compose, ejecuta docker compose up de nuevo).

gemini-3.6-flash has no requests left on this API key right now. Pick a different model from the list above the chat, or try again in a few minutes.

El proveedor rechazó la petición porque la cuota de la clave se agotó, algo habitual con una clave gratuita. Elige otro modelo en el selector o inténtalo más tarde.

• El asistente de IA

No se puede subir una imagen

Image uploads are not set up on this server yet. Add the Cloudflare R2 settings to the API environment to turn them on.

Las fotos de perfil y los archivos de imagen adjuntos del asistente se guardan en un bucket de Cloudflare R2. Define las cinco variables R2_* en back-end/.env y reinicia la API. Todo lo demás funciona sin ellas.

• Subida de imágenes

El saludo no muestra el tiempo

El tiempo del saludo del resumen necesita una clave de WeatherAPI.com en WEATHER_API_KEY, que lee el propio servidor del panel. Sin ella, el saludo se muestra sin el tiempo y nada más cambia.

• Sin Docker, en el .env del panel, y luego reinicia.
• Con Docker Compose, en el .env junto a docker-compose.yml, y luego docker compose up de nuevo.
• Con la imagen del panel, en docker run: -e WEATHER_API_KEY=....

MySQL no arranca o no carga los datos

La API crea sus tablas en una base de datos que ya existe; no crea la base de datos en sí. Crea primero una base de datos vacía, da su nombre a DB_DATABASE en back-end/.env y luego ejecuta yarn seed.

• Revisa los cinco valores de conexión DB_* y que DB_TYPE=mysql.
• Con NODE_ENV=production, la API en marcha nunca crea tablas, así que yarn seed:prod tiene que ejecutarse una vez después de yarn build, antes del primer inicio.
• La imagen de Docker crea la base de datos por sí sola solo en SQLite. En MySQL, ejecuta tú mismo node dist/database/seeder.js una vez en el contenedor.

• Usa MySQL en lugar de SQLite

El contenedor de la API no encuentra su entrypoint

exec /usr/local/bin/docker-entrypoint.sh: no such file or directory

El script tiene finales de línea de Windows, que un editor o Git en Windows pueden añadir. El Dockerfile de la API incluido los elimina durante la construcción, así que esto solo aparece con una imagen construida a partir de un Dockerfile modificado. Conserva su línea sed -i 's/\r$//', o guarda el script con finales de línea LF, y vuelve a construir sin la caché.

La carpeta se ve diferente

Ejecuta los comandos dentro de la carpeta en la que se extrae el ZIP. Si no tienes el comando unzip, extráelo con tu gestor de archivos; algunas herramientas añaden una carpeta extra con el nombre del ZIP, así que entra en la carpeta interior.

Empieza de nuevo con datos de ejemplo limpios

Con Full Stack en Docker, desde la carpeta dashboard-2-full-stack:

docker compose down -v
docker compose up

Sin Docker, detén la API y luego, en back-end:

rm -f database.sqlite* && yarn seed

En PowerShell:

Remove-Item database.sqlite*; yarn seed

Restablece los datos de ejemplo en la API simulada

En la API simulada integrada, los datos de ejemplo y todo lo que cambiaste viven en tu navegador. Borra los datos del sitio para la dirección del panel en los ajustes de tu navegador y recarga: los ejemplos vuelven tal como se entregaron.