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 el paquete Full Stack, o tus comandos docker build y docker run para una sola aplicación.

Un puerto ya está en uso

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

Las dos primeras líneas vienen de Docker, la última de yarn dev. Otro programa ya escucha en 3030, 3031 o 8000: a menudo una ejecución anterior de Ticketory, 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 :3031

   En Windows, en PowerShell:

   TerminalCopiar

   netstat -ano | findstr :3031
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 Ticketory de nuevo.
3. 03

   O ejecuta Ticketory en otros puertos

   Con la pila completa en Docker, crea un archivo llamado .env en la carpeta ticketory-full-stack, junto a docker-compose.yml, con el puerto que necesites. SITE_PORT mueve el sitio web, ADMIN_PORT el panel y API_PORT la API; las direcciones que usan las aplicaciones, CORS_ORIGIN incluido, siguen solas.

   ticketory-full-stack/.envCopiar

   ADMIN_PORT=3041

   Luego ejecuta el mismo comando otra vez. Un inicio fallido continúa donde se detuvo. Docker nombra un solo puerto ocupado cada vez: si se detiene en otro, añade ese también al .env.

   Terminalen ticketory-full-stackCopiar

   docker compose up --build

   Resultado esperado: La aplicación responde en su nuevo puerto, aquí localhost:3041Local.

La construcción de Docker falla

La primera construcción descarga las imágenes base y todas las dependencias, y luego construye las imágenes. Si algo lo impide, se detiene con "failed to solve" y el paso que falló.

• 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.
• Compose rechaza el propio `docker-compose.yml`, nombrando `env_file`: tu Compose es anterior a la 2.24. Actualiza Docker Desktop, o el plugin de Compose en Linux.

docker compose build --no-cache
docker compose up

En un paquete de una sola aplicación, añade --no-cache a tu comando docker build.

Un primer inicio que parece atascado suele seguir creando los organizadores de ejemplo. El sitio web y el panel arrancan solo cuando la API informa de que está sana.

Yarn dice que su versión es 1.22

This project's package.json defines "packageManager": "yarn@4…". 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 otra vez. Si tu Node.js no tiene Corepack (Node.js 25 y posteriores lo omiten), instálalo antes con npm install -g corepack. No se usan npm ni pnpm: cada aplicación incluye su propio yarn.lock.

Una instalación o un inicio falla con una versión antigua de Node.js

Cada aplicación declara Node.js 22 o más reciente, y las imágenes de Docker funcionan con Node.js 24. Un Node.js más antiguo se nota en una instalación que no logra construir un paquete, o en una aplicación que se detiene al iniciar.

node -v

Si muestra una versión inferior a la 22, instala Node.js 22 o más reciente, ejecuta corepack enable otra vez (en Node.js 25 y posteriores, antes npm install -g corepack), luego 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 website and organiser dashboard origins, comma separated, …

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 la carpeta de la API 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`. Escribe las direcciones del sitio web y del panel, separadas por comas.

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.

• Lo esencial de la API

El sitio web no tiene eventos y nadie puede iniciar sesión

→ No database at /data/database.sqlite. Creating the tables, no data (set SEED_DEMO_DATA=true for the demo).

La base de datos se creó solo con las tablas. Ocurre cuando el contenedor de la API arranca sobre un volumen nuevo sin SEED_DEMO_DATA=true, cuando la pila completa se ejecuta con SEED_DEMO_DATA=false en el .env junto a docker-compose.yml, o, sin Docker, cuando se ejecutó yarn db:sync en lugar de yarn seed. No hay eventos ni cuenta del panel con la que iniciar sesión.

• Sin Docker: ejecuta yarn seed en la carpeta de la API. Añade los organizadores de ejemplo y sus cuentas a las tablas que ya tienes.
• Pila completa en Docker: quita SEED_DEMO_DATA=false del .env, luego ejecuta docker compose down -v y docker compose up. El volumen de datos se crea de nuevo con los datos de ejemplo.
• Contenedor de la API: elimina el contenedor, borra su volumen y vuelve a ejecutarlo con -e SEED_DEMO_DATA=true, como en Empieza de cero con datos de demostración nuevos, más abajo.
• Para tu propio espacio de trabajo en lugar de los datos de ejemplo: define OWNER_EMAIL y OWNER_PASSWORD (de al menos 10 caracteres) e inicia la API de nuevo sobre esa base de datos vacía. Su registro dirá Clean start: created the workspace; mientras no estén definidas, dice qué variables definir.

El contenedor nunca vuelve a cargar datos en una base de datos existente, diga lo que diga SEED_DEMO_DATA, así que la variable solo importa en un volumen nuevo.

• Puesta en marcha con tu propio espacio de trabajo

El inicio de sesión falla

• Revisa la cuenta y la aplicación. El personal inicia sesión en el panel en el puerto 3031 (owner@example.test, manager@example.test, finance@example.test, checkin@example.test); el asistente attendee@example.test inicia sesión en el sitio web en el puerto 3030, nunca en el panel. Todas las cuentas de ejemplo usan la contraseña DemoOnly!2026.
• "Invalid email or password" en el panel responde igual a una contraseña incorrecta, a un correo desconocido y a una base de datos sin cuentas. Revisa los puntos de abajo por orden.
• La base de datos no tiene cuentas cuando se creó con SEED_DEMO_DATA=false y sin variables del propietario. Mira El sitio web no tiene eventos y nadie puede iniciar sesión, arriba.
• "Too many sign-in attempts. Try again in a few minutes." Diez inicios de sesión fallidos desde una misma dirección en 15 minutos bloquean el formulario para esa dirección hasta que el fallo más antiguo cumpla 15 minutos. El inicio de sesión del sitio web cuenta igual. Espera, o reinicia la API: el recuento se guarda en su memoria.
• "Network error. Check your connection and try again." significa que el panel no puede llegar a la API: mira el problema de CORS de abajo.
• Cambiaste una contraseña y ya no la tienes: empieza de nuevo con datos de demostración nuevos, más abajo.

El inicio de sesión falla

• Revisa la cuenta y la ruta. El personal inicia sesión en POST /api/auth/login (el propietario de ejemplo es owner@example.test), los asistentes en POST /api/customer-auth/login (attendee@example.test); todas las cuentas de ejemplo usan DemoOnly!2026. Un inicio de sesión fallido responde 401 con el mismo mensaje tanto si falla el correo como la contraseña.
• Ninguna cuenta funciona: la base de datos se creó sin los datos de ejemplo. Ejecuta yarn seed, o inicia el contenedor con -e SEED_DEMO_DATA=true sobre un volumen nuevo. En tu propia instalación, el propietario es el OWNER_EMAIL que se dio en el primer inicio.
• Una respuesta `429` significa que una dirección falló 10 inicios de sesión en 15 minutos. Se levanta cuando el fallo más antiguo cumple 15 minutos, o cuando la API se reinicia. RATE_LIMIT_LOGIN cambia el número.

El inicio de sesión falla

Tu aplicación inicia sesión en la API de Ticketory, así que la cuenta tiene que existir allí. En una API con datos de ejemplo, el personal inicia sesión en el panel con owner@example.test y los asistentes en el sitio web con attendee@example.test, ambos con DemoOnly!2026. Si ninguna cuenta funciona, o bien la API se inició sin sus datos de ejemplo (ejecuta yarn seed en su carpeta, o inicia su contenedor sobre un volumen nuevo con -e SEED_DEMO_DATA=true), o bien la aplicación no llega a la API: mira el siguiente problema.

El código de registro o un correo de entradas nunca llega

Mientras RESEND_API_KEY y MAIL_FROM no estén definidos en el .env de la API, no se envía ningún correo. Todos (el código de registro de 6 dígitos, los restablecimientos de contraseña, las entradas, las novedades de reembolso y los recordatorios de eventos) se escriben en el registro de la API, empezando con esta línea:

Mail not sent (no provider configured). Message follows:

• Pila completa en Docker: ejecuta docker compose logs api en la carpeta del paquete y lee el código del mensaje más reciente.
• Sin Docker: léelo en la terminal donde se ejecuta el yarn dev de la API.
• Contenedor de la API: docker logs con el id del contenedor (docker ps lo muestra).
• Para enviar correo real, define las dos variables con una clave de Resend y un remitente de un dominio que hayas verificado en Resend, y luego reinicia la API.

Las páginas dicen "We could not load this right now"

We could not load this right now
Access to XMLHttpRequest at 'http://localhost:8000/api/…' from origin 'http://localhost:3041' has been blocked by CORS policy

El sitio web muestra la primera línea, y el panel dice "Network error", cuando el navegador no puede usar la API. La consola del navegador muestra la segunda línea cuando un frontend 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 y http://localhost:3031. Un sitio web o un panel movido a otro puerto, o servido en tu propio dominio, es rechazado hasta que figure en la lista.

CORS_ORIGIN=http://localhost:3030,http://localhost:3041
FRONTEND_URL=http://localhost:3041

• Escribe cada dirección exactamente como la muestra el navegador, con el esquema y el puerto y sin barra final, separadas por comas. Luego reinicia la API.
• FRONTEND_URL es la dirección del panel, desde la que se conectan sus notificaciones en directo. Muévela junto con el panel.
• Para un contenedor de la API, pasa los mismos valores con -e, por ejemplo -e CORS_ORIGIN=http://localhost:3030,http://localhost:3041.
• Con el paquete completo en Docker no editas estos valores: los configuran SITE_PORT, ADMIN_PORT, SITE_URL y ADMIN_URL en el .env junto a docker-compose.yml.
• Un frontend que no llega a la API en absoluto, porque está detenida o en otra dirección, falla de la misma forma pero sin la línea de CORS. Comprueba que localhost:8000/api/healthLocal responde y que NEXT_PUBLIC_API_BASE_URL del frontend apunta a esa API.

• Despliégalo

La pestaña de una página de evento muestra solo el nombre del sitio en Docker

El propio servidor del sitio web lee el título del evento para la pestaña del navegador, el primer renderizado de las páginas de inicio, evento, recinto y organizador, y el mapa del sitio. Dentro de un contenedor, localhost es el propio contenedor, así que ese servidor no puede llegar a una API de tu equipo en http://localhost:8000. La página sigue cargando en el navegador, que llega a la API directamente.

Inicia el contenedor del sitio web con la dirección de la API tal como la ve el servidor:

docker run -p 3030:3030 -e API_INTERNAL_URL=http://host.docker.internal:8000/api --add-host=host.docker.internal:host-gateway ticketory-website

La pila completa en Docker lo define por ti (http://api:8000/api). Sin Docker no hace falta.

Las imágenes de los eventos no cargan

La API sirve las imágenes de ejemplo en /media/ticketory/…, y cada dirección de imagen se construye a partir de PUBLIC_MEDIA_URL, que por defecto es http://localhost:8000/media. Una imagen se rompe cuando esa dirección no llega a la API desde el navegador.

• La API funciona en otro puerto o dominio. Configura PUBLIC_MEDIA_URL con la dirección pública de la API seguida de /media, por ejemplo -e PUBLIC_MEDIA_URL=http://localhost:8010/media con docker run -p 8010:8000. Con el paquete completo en Docker, API_PORT y API_URL lo configuran por ti.
• La API cambió de dirección después del primer inicio. Reiníciala con el nuevo PUBLIC_MEDIA_URL: al arrancar, apunta todas las imágenes guardadas a esa dirección, y su registro dice "Pointed … stored media URLs at …".
• Los archivos subidos a un bucket no cargan. R2_PUBLIC_URL debe ser la dirección pública del bucket, y el bucket debe permitir lecturas públicas.
• Las imágenes cargan, pero a tamaño completo. Los frontends solo redimensionan imágenes de los hosts https de NEXT_PUBLIC_MEDIA_HOSTNAME (con Docker Compose, MEDIA_HOSTNAME), cada uno escrito solo como host y separados por comas, como api.your-domain.com,pub-1234.r2.dev. Cualquier otra imagen, como una de una API en localhost, se carga tal cual. Vuelve a construir el frontend después de cambiarlo.

• Variables de entorno

El pago ofrece solo Test payment, o me devuelve atrás

Your reservation expired. Choose seats again.

• Solo se ofrece Test payment. La API aún no tiene una clave real de Stripe ni de PayPal, así que ofrece el simulador de pagos, que marca un pedido como pagado sin mover dinero. Añade tus claves al .env de la API y reiníciala; PAYMENTS_SIMULATOR=on o off ahí anula la elección. Las entradas gratuitas no muestran ningún método de pago: se confirman con Get tickets.
• "Your reservation expired". Los asientos elegidos se reservan durante el tiempo de reserva del espacio de trabajo, diez minutos en los datos de ejemplo, según el reloj del servidor. Elige los asientos de nuevo para empezar una nueva reserva.
• El pago te devuelve a los eventos. La pestaña del navegador no tiene asientos reservados: el pago se abrió en otra pestaña (una reserva pertenece a la pestaña que la hizo), o la API ya no conoce la reserva. Elige los asientos de nuevo.
• Un pago con Stripe o PayPal se queda en "Confirming your payment". La página pregunta a la API, que pregunta al proveedor, hasta que el pago se confirma. En un servidor, registra los webhooks en /api/webhooks/stripe y /api/webhooks/paypal para que las confirmaciones lleguen al instante, y comprueba que STOREFRONT_URL y PUBLIC_API_URL son las direcciones que usa el navegador del comprador.

Un cambio en el .env de un frontend 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.

El estudio de recintos o el asistente piden una clave

Generation needs a Google Gemini key
The assistant needs an AI provider key

El asistente responde con Google Gemini, OpenAI o DeepSeek y se activa con la clave de cualquiera de ellos en el .env de la API: GOOGLE_API_KEY, OPENAI_API_KEY o DEEPSEEK_API_KEY, las tres que enumera su aviso. El estudio de recintos genera solo con Google, así que necesita GOOGLE_API_KEY sea cual sea el resto. En .env.example las tres líneas están comentadas, así que un archivo copiado arranca limpio y ambas funciones quedan desactivadas, sin cobrar nada.

• Quita el # delante de la línea de cada clave que tengas, pega tu clave real sobre el ejemplo y reinicia la API.
• Con Docker Compose la API también lee back-end/.env, así que basta con docker compose up otra vez; un contenedor de API suelto necesita --env-file .env -e NODE_ENV=production en su docker run.
• Recarga la página del panel después del reinicio.
• Un modelo que falta en el selector del asistente pertenece a un proveedor cuya clave no está definida: el selector solo enumera los modelos de los proveedores con clave.

El asistente no puede responder con el modelo elegido

{provider} did not accept the API key, so {model} could not answer. Check that {variable} holds a valid {provider} key, then try again or pick a model from another provider.
The {provider} account behind this API key has no credit left, so {model} could not answer. Add credit or billing on that account, or pick a model from another provider.
{model} 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.
{provider} has no room for {model} right now. Try again in a minute, or pick another model from the list above the chat.

El asistente muestra uno de estos mensajes en lugar de una respuesta cuando el proveedor del modelo elegido rechaza la petición, con Google, OpenAI o DeepSeek como proveedor, el nombre del modelo y la variable de la clave rellenados. Solo ejecuta el modelo que elegiste: nunca cambia a otro por sí solo ni reintenta por su cuenta, así que corrige la causa o elige otro modelo en la lista sobre el chat y luego pulsa Try again.

En modo demostración, el asistente pide la clave propia del visitante

Se rechaza el formulario de contacto o el registro

Too many requests were sent from this connection. Please wait a few minutes and try again.

• Too many requests. Cada dirección puede enviar cinco formularios de contacto en diez minutos, iniciar diez registros y pedir cinco restablecimientos de contraseña en ese mismo tiempo. Mientras pruebas, espera, o reinicia la API: los recuentos viven en su memoria.
• Un campo que la API no conoce. El registro rechaza con 400 un cuerpo con campos desconocidos y los nombra. Solo ocurre con tu propio cliente o un formulario modificado: envía los campos que envía el sitio web.
• Detrás de un proxy inverso, todos los visitantes pueden parecer el proxy y compartir una misma cuota: consulta el siguiente problema.

Todos los visitantes reciben "Too many" detrás de un proxy

El inicio de sesión, el registro, el formulario de contacto y los escaneos de la puerta se limitan por dirección. Detrás de un proxy inverso, todos los visitantes pueden parecer la única dirección del proxy y compartir una misma cuota. Indica a la API cuántos proxies hay delante:

TRUST_PROXY=1

RATE_LIMIT_LOGIN cambia el número de inicios de sesión fallidos permitidos. Cada lector de la puerta puede hacer 120 comprobaciones por minuto. Los recuentos viven en la memoria de la API, así que un reinicio los borra.

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, pon su nombre en DB_DATABASE en el .env de la API y luego ejecuta yarn seed (o yarn db:sync para las tablas sin datos de demostración).

• Revisa los cinco valores de conexión DB_* y que DB_TYPE=mysql.
• Con NODE_ENV=production la API en ejecución nunca crea tablas, así que uno de esos comandos tiene que ejecutarse antes del primer inicio (yarn seed:prod o yarn db:sync:prod después de yarn build).
• La imagen de Docker crea la base de datos por sí sola solo con SQLite. Con MySQL, ejecuta tú mismo una vez la carga de datos o el comando del esquema.

• 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é.

El comando unzip falla o la carpeta se ve distinta

caution: filename not matched:  ticketory-…zip

Ese mensaje significa que hay dos ZIP del mismo paquete en la carpeta, como una descarga anterior junto a la nueva, y el * del comando coincidió con ambos. Elimina el ZIP más antiguo y ejecuta el comando otra vez, o escribe el nombre completo del archivo en lugar del *.

Ejecuta los siguientes comandos dentro de la carpeta en la que se extrae el ZIP. Si falta 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 interior.

Empieza de cero con datos de demostración nuevos

Con la pila completa en Docker, desde la carpeta ticketory-full-stack:

docker compose down -v
docker compose up

Con un único contenedor de la API, elimina primero el contenedor (docker ps -a lo muestra, docker rm -f con su id lo elimina), luego borra el volumen ticketory-api-data y ejecútalo de nuevo. La pila completa guarda sus datos en otro volumen, ticketory-data, así que esto nunca lo toca.

docker volume rm ticketory-api-data
docker run -p 8000:8000 -v ticketory-api-data:/data -e SEED_DEMO_DATA=true ticketory-api

Sin Docker, detén la API y luego, en su carpeta:

rm -f database.sqlite* && yarn seed

En PowerShell:

Remove-Item database.sqlite*; yarn seed

Ejecutar yarn seed otra vez sobre una base de datos que conservas no es un restablecimiento: no añade filas y nunca restablece una contraseña, pero devuelve los cuatro roles integrados a sus permisos por defecto. yarn db:reset borra todas las tablas, tanto en SQLite como en MySQL; ejecuta yarn seed después.