Errores comunes
Aquí están los fallos más probables, con el síntoma exacto y qué hacer.
🤖 Si tu error no está aquí, pégaselo a Kiro
Copia el error completo y el comando que lo produjo, y pídele que te explique qué pasó sin desplegar ni borrar nada. Si la respuesta no te sirve, cambia de modelo en el selector del chat y vuelve a preguntar. Está explicado en la introducción.
No encuentro package.json después de clonar
Síntoma: npm install dice que no encuentra package.json.
Qué pasó: la terminal no está en la carpeta que creó git clone. También
puede haber una carpeta workshop-altar-digital dentro de otra con el mismo
nombre si ejecutaste el clonado desde una carpeta que ya tenía ese nombre.
Arreglo: localiza la carpeta que contiene package.json, entra ahí y corre
git remote -v. Si las URLs apuntan a tu usuario, ya estás en el lugar correcto;
no vuelvas a clonar.
Las Lambdas responden 500 o 502
Síntoma: el deploy pasó, pero cualquier petición a la API falla. En los logs
de CloudWatch sale Cannot use import statement outside a module.
Qué pasó: falta lambda/package.json, el archivo de tres líneas que dice que
esa carpeta son módulos.
Los handlers usan import, o sea ESM. Lambda los carga como CommonJS a menos que
la carpeta lo declare. Y el package.json de la raíz no sirve, porque lo que se
empaqueta y se sube a Lambda es solo la carpeta lambda/: el de la raíz
nunca llega.
Arreglo: que exista ese archivo, y vuelve a desplegar. No lo borres pensando que está de más, que es exactamente lo que invita a hacer.
El altar en producción sigue guardando en el navegador
Síntoma: ya pusiste VITE_API_URL en Amplify, pero el banner del altar sigue
diciendo que guarda en el navegador.
Qué pasó: el banner sale de MODO dentro de
web/src/datos/almacen.js, no de la variable de Amplify. Si todavía dice
navegador, ese archivo no se reescribió para la API o el cambio no llegó a la
rama main. Si ya dice nube pero no conecta, el build puede ser anterior a
VITE_API_URL.
Arreglo: confirma que almacen.js tenga MODO = 'nube' y lea
import.meta.env.VITE_API_URL, haz commit y push de ese archivo, configura la
variable en Amplify y ejecuta un redeploy.
El deploy rebota por la Región
Síntoma: el deploy falla diciendo que no estás autorizado, o que la operación no está disponible ahí.
Qué pasó: estás desplegando en una Región que no es la de tu proyecto. En la nueva experiencia de AWS solo puedes crear recursos en tu Región.
Arreglo: confírmala en AWS Settings y vuelve a intentar con esa.
cdk deploy pide bootstrap
Síntoma: dice que el ambiente no tiene bootstrap.
Arreglo: córrelo con el perfil del workshop. Igual en Windows, macOS y Linux:
npx cdk bootstrap --profile ofrenda
curl se comporta raro en Windows
Síntoma: copias un comando con curl en PowerShell y la sintaxis no le
gusta, o te sale un aviso de seguridad.
Qué pasó: en PowerShell 5.1, curl no es curl: es un alias de
Invoke-WebRequest, que es otro programa con otra sintaxis.
Arreglo: escribe curl.exe en lugar de curl. Así funciona igual en
PowerShell, en CMD y en Git Bash.
El build de Amplify dice "vite: command not found"
Síntoma: el build falla en la fase de build con sh: vite: command not found y
Command failed with exit code 127. Arriba, en la fase de preBuild, dice algo como
added 3 packages.
Qué pasó: el preBuild instaló las dependencias con --omit=dev, y Vite vive en
devDependencies. Sin Vite no hay quien construya, aunque tu código esté bien. Ese
added 3 packages es la pista: son React, React DOM y una dependencia suya, nada más.
Arreglo: en amplify.yml, el comando de preBuild tiene que ser npm ci, sin
--omit=dev.
devDependencies no significa "solo en mi laptop". Significa que la dependencia
no hace falta para correr los archivos ya publicados. El contenedor de Amplify
construye el sitio y por eso sí necesita Vite.
El build de Amplify usa una versión incorrecta de Node
Síntoma: el build falla antes de transformar archivos y el log muestra una versión de Node anterior a 24.11.
Qué pasó: la imagen de Amplify tiene una versión predeterminada propia. El
amplify.yml del starter corre nvm install 24.21.0 y
nvm use 24.21.0 antes de
npm ci; si esas líneas se borraron, el build vuelve a depender de la imagen.
Arreglo: restaura esas líneas y confirma en el log que node --version
imprime v24.21.0.
Amplify construye pero publica una página en blanco
Síntoma: el build sale verde y la URL carga en blanco.
Qué pasó: casi siempre, que amplify.yml apunta a la carpeta equivocada. El
build de Vite escribe en dist/.
Arreglo: revisa que amplify.yml tenga dist como carpeta de artefactos, y
que no lo hayas cambiado.
El push no me deja entrar
Síntoma: Git pide usuario y contraseña, y tu contraseña de GitHub no sirve.
Qué pasó: GitHub ya no acepta contraseñas para Git. Hace falta un token o el login por navegador.
Arreglo: usa la ventana de login del navegador o pide ayuda en la mesa para configurar un token de GitHub.
Me atoré y el grupo ya avanzó
No te quedes atrás callado. Los módulos 3 y 4 tienen ramas de rescate, y los
comandos para copiar su solución a main están en
Comandos del repo.
Cambiar a la rama de rescate no es rendirse: es seguir el taller con el backend ya resuelto, que es donde está el resto del aprendizaje.