Solución de problemas

Una referencia con el síntoma, la causa y la corrección de todos los fallos observados al crear y probar este taller, agrupados por el lugar en el que aparecen.

Los comandos de esta página usan los valores guardados en .env.workshop.

Todas las entradas siguientes corresponden a fallos que realmente ocurrieron durante la creación y las pruebas de este taller. Busca tu síntoma, comprende la causa y aplica la corrección. Si no hay ninguna coincidencia, entrega el problema a tu agente de programación: la guía para realizar el taller a tu ritmo incluye un prompt listo para pegar que lo convierte en tu instructor.

Windows y WSL 2

`wsl --install` no está disponible o solo muestra la ayuda

Síntoma: PowerShell como administrador no reconoce wsl --install o muestra la ayuda en lugar de instalar Ubuntu.
Causa: la versión de Windows no cumple el mínimo del taller, hay actualizaciones pendientes sin aplicar o la política corporativa deshabilita WSL.
Corrección: ejecuta Windows Update y confirma que utilizas Windows 11 o Windows 10 versión 2004 (compilación 19041) o posterior. Reinicia y sigue los pasos de instalación manual de WSL de Microsoft. En un equipo administrado, un administrador debe permitir las características necesarias de Windows.

Un comando «no se reconoce» en PowerShell

Síntoma: PowerShell rechaza ./preflight.sh, export, source u otro comando Bash del taller.
Causa: la configuración de Windows solo usa PowerShell para la preparación de WSL que está etiquetada expresamente. Los comandos del taller se ejecutan dentro de Ubuntu en WSL 2.
Corrección: abre Ubuntu desde el menú Inicio, vuelve al directorio de la aplicación y ejecuta allí la comprobación previa:
```
cd ~/ClickHouse_Demos/workshops/build_workshop/app
./preflight.sh
```

El repositorio está en `/mnt/c`

Síntoma: los montajes enlazados de Docker son lentos, los scripts presentan errores de permisos o finales de línea, o la ruta del repositorio empieza por /mnt/c/Users/....
Causa: el repositorio se clonó en el sistema de archivos de Windows, en lugar del sistema de archivos Linux de WSL.

Corrección: conserva la copia antigua solo si necesitas trabajo que aún no hayas guardado. De lo contrario, abre Ubuntu y clona una copia limpia en tu directorio personal de Linux:

cd ~
git config --global core.autocrlf input
git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd workshops/build_workshop/app
cp .env.workshop.example .env.workshop

Ubuntu se ejecuta como WSL 1

Síntoma: wsl --list --verbose muestra Ubuntu con VERSION 1, o Docker Desktop no puede integrarse con la distribución.
Causa: la distribución es anterior a WSL 2 o se instaló con WSL 1 como valor predeterminado.
Corrección: abre PowerShell como administrador, conviértela y vuelve a abrir Ubuntu:
```
wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --list --verbose
```

`docker` no está disponible dentro de Ubuntu

Síntoma: Docker Desktop está en ejecución, pero Ubuntu indica docker: command not found o no puede acceder al daemon.
Causa: el motor WSL de Docker Desktop o la integración con Ubuntu está deshabilitada.
Corrección: activa Docker Desktop -> Settings -> General -> Use the WSL 2 based engine y Resources -> WSL Integration -> Ubuntu, aplica el cambio y ejecuta wsl --shutdown en PowerShell. Después, vuelve a abrir Ubuntu. docker version debe mostrar las secciones Client y Server.

WSL o Docker dispone de menos de 6 GB de memoria

Síntoma: la comprobación previa indica memoria insuficiente, o docker info --format 'Docker memory: {{.MemTotal}} bytes' muestra menos de 6442450944 bytes.
Causa: el back-end WSL 2 de Docker Desktop usa el límite de memoria de la máquina virtual de WSL.
Corrección: cierra Docker Desktop, abre PowerShell y establece un límite de 8 GB para WSL:
```
@('[wsl2]', 'memory=8GB', 'processors=4') |
  Set-Content -Encoding ascii "$env:USERPROFILE\.wslconfig"
wsl --shutdown
```
Inicia Docker Desktop y vuelve a abrir Ubuntu. Ejecuta de nuevo el comando docker info y la comprobación previa.

Un script muestra `/usr/bin/env: 'bash\r': No such file or directory`

Síntoma: un archivo .sh falla de inmediato y el error incluye bash\r o ^M.
Causa: los finales de línea CRLF de Windows sustituyeron los finales LF que necesita el repositorio.
Corrección: en Ubuntu, configura la política de Git para WSL y restaura un checkout limpio:
```
git config --global core.autocrlf input
git status --short
git add --renormalize .
```
Revisa git status antes de descartar o guardar nada. Si el checkout no contiene trabajo que necesites, un clon limpio en ~/ClickHouse_Demos es la recuperación más segura.

OAuth no abre el navegador de Windows

Síntoma: un inicio de sesión de MCP muestra una URL, pero no se abre ninguna ventana del navegador.
Causa: el agente de programación se ejecuta dentro de WSL y el reenvío al navegador no está disponible o está bloqueado por la política corporativa.
Corrección: copia la URL de inicio de sesión completa desde Ubuntu y pégala en el navegador habitual de Windows. Completa allí la autorización y vuelve a la terminal de Ubuntu.

Docker

Los contenedores se quedan en «Created» y nunca se inician

Síntoma: docker info responde correctamente, pero docker compose ... up deja los contenedores en Created y ninguno llega a estar en buen estado.
Causa: el motor de Docker se ha bloqueado; el daemon responde, pero no puede iniciar un contenedor. Se observó con OrbStack durante una preparación en directo.
Corrección: reinicia el motor de Docker (Docker Desktop, OrbStack o Colima) y espera hasta que indique Running; después, vuelve a iniciar la pila. Desde cualquier punto del repositorio clonado, ejecuta cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh; detecta este problema antes de iniciar la pila ejecutando un contenedor desechable como prueba.

«port is already allocated» al iniciar

Síntoma: docker compose ... up falla con Bind for 0.0.0.0:8080 failed: port is already allocated (o :8000).
Causa: otro proceso o un contenedor antiguo del taller ya ocupa ese puerto del host.
Corrección: desde cualquier punto del repositorio clonado, ejecuta cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh. El script indica qué ocupa el puerto y muestra la sustitución exacta que debes definir, siguiendo la convención puerto base + 20000, por ejemplo, set FRONTEND_HOST_PORT=28080 in .env.workshop. Las variables de sustitución son FRONTEND_HOST_PORT, BACKEND_HOST_PORT y, para la superposición de observabilidad, OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT. Define el valor sugerido, ejecuta de nuevo la comprobación previa e inicia la pila. Solo cambian los puertos del host; los puertos internos de los contenedores no varían, por lo que es seguro.

Advertencia «platform does not match»

Síntoma: Docker muestra una advertencia de incompatibilidad de plataforma (por ejemplo, linux/amd64 frente a linux/arm64) al descargar o iniciar una imagen.
Causa: la imagen se creó para una arquitectura de CPU distinta a la del equipo, algo habitual en Apple Silicon.
Corrección: no supone ningún problema. Es una advertencia, no un fallo; la imagen se ejecuta mediante emulación. Deja que continúe.

ClickHouse Cloud

La primera solicitud tras un periodo de inactividad es lenta o devuelve 500 una vez

Síntoma: la primera consulta o carga del panel después de que el servicio haya estado inactivo es lenta, o una solicitud devuelve 500 una vez y después funciona.
Causa: un servicio de Cloud reduce la escala a cero cuando está inactivo y tarda unos 30 segundos en reactivarse; la primera solicitud asume ese coste. El back-end ya permite un timeout mayor en la primera conexión y hace un reintento.
Corrección: repite el intento o espera unos 30 segundos. No es un fallo. También es relevante en 07 Probar, fallar y corregir: un servicio que se está reactivando hace que el timeout del fallo 03 se produzca con mayor facilidad.

Se perdió la contraseña del servicio

Síntoma: no guardaste la contraseña del usuario default y no puedes encontrarla.
Causa: la contraseña del servicio no vuelve a mostrarse tras salir del proceso de creación.
Corrección: abre el servicio, ve a Settings y restablece la contraseña del usuario default; después, actualiza CLICKHOUSE_PASSWORD en .env.workshop. El host siempre está disponible en el cuadro Connect.

Se perdió la contraseña de Postgres administrado

Síntoma: no guardaste la contraseña de administrador de un solo uso del usuario postgres que devolvió clickhousectl cloud postgres create.
Causa: solo se muestra una vez, y las API beta postgres get / list pueden devolver vacío o FORBIDDEN incluso cuando la instancia está en buen estado.
Corrección: ejecuta clickhousectl cloud postgres reset-password <service-id> y usa la nueva contraseña en .env.workshop (PGPASSWORD) y en la conexión de ClickPipe.

No se puede acceder a ClickHouse Cloud

Síntoma: la comprobación previa marca como FAIL la conectividad, o el back-end no puede conectarse; the command below falla.

CLICKHOUSE_HOST=$(sed -n 's/^CLICKHOUSE_HOST=//p' .env.workshop | tail -n 1)
CLICKHOUSE_PORT=$(sed -n 's/^CLICKHOUSE_PORT=//p' .env.workshop | tail -n 1)
curl "https://$CLICKHOUSE_HOST:$CLICKHOUSE_PORT/ping"

Causa: wifi, VPN o cortafuegos; un host incorrecto (se pegó un esquema o puerto en CLICKHOUSE_HOST); una discrepancia de TLS o puerto; o una lista de acceso por IP de Cloud que bloquea tu dirección.
Corrección: confirma que CLICKHOUSE_HOST contiene solo el nombre de host (sin https:// ni puerto), CLICKHOUSE_PORT=8443 y CLICKHOUSE_SECURE=true; comprueba la VPN y el cortafuegos; confirma que la lista de acceso por IP del servicio permite tu dirección. La comprobación previa identifica el fallo concreto: DNS, rechazo, timeout o protocolo de enlace TLS.

El cliente muestra `Unknown settings: ... skipping`

Síntoma: las consultas funcionan, pero cada invocación muestra una advertencia de configuración desconocida.
Causa: el cliente local es más reciente que el servidor en la nube y envía una opción que esa versión del servidor no reconoce.
Corrección: repite los comandos para instalar el cliente correspondiente del paso 6 del módulo 00. Leen la versión del servidor en la nube mediante clickhousectl y seleccionan la versión principal y secundaria correspondiente del cliente. No ocultes todas las advertencias del cliente mediante --no-warnings.

CDC (módulo 03)

La creación de ClickPipe indica `table realtime_trips exists and is not empty`

Síntoma: no existe ningún recurso ClickPipe, pero al volver a crearlo falla porque default.realtime_trips ya contiene filas.
Causa: eliminar un ClickPipe borra su ranura de replicación de origen, pero puede dejar la tabla de destino. Un pipe nuevo no sobrescribe esa tabla si no está vacía.

Corrección: conserva las filas sin procesar antiguas con nombres de copia de seguridad que incluyan una marca de tiempo y vuelve a crear el pipe. Sustituye una vez el marcador del ID de servicio; estos comandos también conservan la vista materializada anterior si existe:

CH_SERVICE_ID=<clickhouse-service-id>
BACKUP_SUFFIX=$(date -u +%Y%m%d%H%M%S)

if clickhousectl cloud service query --id "$CH_SERVICE_ID" \
  --query "EXISTS TABLE nyc_tlc_data.realtime_trips_to_taxi_trips_mv" | grep -q 1; then
  clickhousectl cloud service query --id "$CH_SERVICE_ID" --query "
    RENAME TABLE nyc_tlc_data.realtime_trips_to_taxi_trips_mv
    TO nyc_tlc_data.realtime_trips_to_taxi_trips_mv_backup_${BACKUP_SUFFIX}
  "
fi

clickhousectl cloud service query --id "$CH_SERVICE_ID" --query "
  RENAME TABLE default.realtime_trips
  TO default.realtime_trips_backup_${BACKUP_SUFFIX}
"

Repite el paso 3 del módulo 03 y espera a que aparezca la nueva tabla default.realtime_trips antes de volver a crear la vista materializada canónica en el paso 4. Elimina las copias de seguridad con marca de tiempo más adelante, solo después de confirmar que ya no necesitas sus datos.

ClickPipe se queda en «Provisioning»

Síntoma: el pipe muestra Provisioning durante un tiempo después de crearlo.
Causa: el snapshot y el inicio de la infraestructura suelen tardar unos minutos, pero pueden tardar más de 10 minutos incluso para esta tabla pequeña.
Corrección: comprueba el progreso en la consola o con ambos comandos, clickhousectl cloud clickpipe list <clickhouse-service-id> y clickhousectl cloud clickpipe get <clickhouse-service-id> <clickpipe-id>. Durante los primeros minutos, sigue esperando mientras avance su estado o el valor updatedAt. Si continúa en Provisioning sin actualizaciones después de 10 minutos, confirma que el registro de pg-trip-writer sigue mostrando inserciones, comprueba de nuevo el host, las credenciales, la publicación y la asignación de tablas, e inspecciona el error indicado por el pipe. No crees un segundo pipe ni la vista materializada mientras el primero siga aprovisionándose. Si las comprobaciones del origen funcionan y Cloud no informa de ningún error que puedas resolver, guarda la salida de get y escala el problema al instructor o al soporte de ClickHouse Cloud.

Las filas no llegan a ClickHouse

Síntoma: el pipe está Running, pero el recuento de filas de destino no aumenta y el panel Ops no cambia.
Causa: el intervalo de sincronización predeterminado es de unos 60 segundos, por lo que cabe esperar cierto retraso; o el generador no está insertando; o no existe la publicación que lee el pipe.
Corrección: espera al menos 60 segundos. Comprueba que el registro de pg-trip-writer muestre inserted N trips y created publication pub_taxi (en tu propia instancia) o publication ... already exists (en una alternativa administrada proporcionada por el instructor). Confirma que el estado del pipe sea Running. Si falta la publicación, el pipe no tiene nada que leer; el generador la crea la primera vez que se ejecuta contra una instancia en la que eres administrador.

La vista materializada no contiene filas

Síntoma: realtime_trips se llena, pero taxi_trips (alimentada por la vista materializada de CDC) permanece vacía.
Causa: la vista materializada se creó antes de que existiera el destino de ClickPipe, o no lee el destino de la CLI en default.realtime_trips.
Corrección: espera a que aparezca la tabla de destino y copia el comando completo de la vista materializada del paso 4 del módulo 03. Verifica primero el origen:
```
clickhousectl cloud service query --id <clickhouse-service-id> --query "
  SELECT database, name, engine
  FROM system.tables
  WHERE name = 'realtime_trips'
"
```
Una vista materializada procesa las filas insertadas después de su creación; mantén el escritor de viajes en ejecución tras crearla.

La ranura de replicación se bloquea

Síntoma: el pipe se detiene y el WAL crece en el Postgres de origen.
Causa: una ranura bloqueada conserva el WAL; una resincronización crea una ranura nueva.
Corrección: en tu propio Postgres administrado (una ranura y margen de sobra), basta con resincronizar el pipe desde la consola. Eliminar un pipe borra su ranura en el origen. Cualquier grupo de respaldo administrado por el instructor es responsabilidad suya; consulta infra/README.md.

Variables de entorno

Una variable exportada del shell prevalece sobre .env.workshop

Síntoma: defines un valor en .env.workshop, pero el contenedor utiliza otro (a menudo un OPENAI_API_KEY, un LANGFUSE_* o un CLICKHOUSE_PASSWORD antiguos).
Causa: docker compose interpola primero ${VAR} desde el shell, y una variable exportada del shell PREVALECE sobre el archivo.
Corrección: en el shell desde el que ejecutas Compose, unset OPENAI_API_KEY LANGFUSE_PUBLIC_KEY LANGFUSE_SECRET_KEY LANGFUSE_BASE_URL CLICKHOUSE_PASSWORD, y vuelve a iniciar la pila. La comprobación previa avisa cuando detecta este caso.

Claves duplicadas en .env.workshop

Síntoma: se ignora un valor que definiste en el archivo.
Causa: la misma clave aparece dos veces; prevalece la última, igual que en la semántica de docker compose (la comprobación previa la lee del mismo modo).
Corrección: elimina el duplicado anterior para que solo quede el valor deseado.

Chat (módulo 08)

POST /api/chat devuelve 503 con una indicación de configuración

Síntoma: el panel de chat muestra una indicación de configuración y /api/chat devuelve 503; el resto de la aplicación funciona correctamente.
Causa: no se ha definido OPENAI_API_KEY en el back-end.
Corrección: añade OPENAI_API_KEY a .env.workshop y ejecuta docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build backend. El chat es la única función que lo necesita.

No se puede crear una primera clave de OpenAI

Síntoma: OpenAI no emite una clave de API en una cuenta nueva.
Causa: las cuentas nuevas requieren una verificación telefónica única y no incluyen créditos gratuitos.
Corrección: completa la verificación telefónica y accede a Settings -> Billing: añade un método de pago y compra el mínimo de 5 USD de crédito prepago. Desactiva la recarga automática (está activada de forma predeterminada durante la configuración) para que nunca se te cobre más de los 5 USD que añadiste.

MCP y OAuth (módulos 00 y 06)

Error 401 en el endpoint MCP

Síntoma: acceder a https://mcp.clickhouse.cloud/mcp (o /clickstack) devuelve 401.
Causa: es lo esperado antes de completar el flujo OAuth en el navegador; el endpoint requiere autenticación.
Corrección: añade el servidor a tu agente, ejecuta el flujo OAuth y autoriza en el navegador mediante el comando de tu herramienta:
- Claude Code: ejecuta /mcp, selecciona el servidor y autoriza (o claude mcp login <name>).
- Codex CLI: codex mcp login <name>.
- Cursor: abre el panel de configuración de MCP y haz clic en el control de autorización o inicio de sesión del servidor.
Confirma también que Connect with MCP está activado en tu servicio.

El portátil corporativo bloquea MCP u OAuth

Síntoma: tu agente no puede añadir un servidor MCP o se bloquea la redirección de OAuth.
Causa: una política del portátil administrado impide añadir servidores MCP o usar OAuth saliente.
Corrección: un equipo personal es la alternativa más rápida.

Windsurf no puede conectarse mediante HTTP nativo

Síntoma: Windsurf no puede conectarse al endpoint MCP o su OAuth es inestable.
Causa: Windsurf se conecta mediante mcp-remote, no mediante HTTP transmisible nativo.
Corrección: usa el formato de comando mcp-remote: { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"] } (sustituye /mcp por /clickstack al conectar ClickStack MCP en el módulo 06).