Tu primera app rota: el bug como rito de iniciación

Anoche jalaba.

Hoy abres la laptop (la vieja, la que suena como secadora cuando corre Docker), levantas el proyecto y te cae un error bien feo. Nada compila, el login no entra o, peor: “sí corre” pero guarda cosas raras. Tienes clase en dos horas / demo con el cliente en la tarde / tu líder ya te puso “¿ya quedó?” y tú viendo el stack trace como si fuera un códice.

Bienvenido a tu primera app rota. No es señal de que “no sirves”. Es señal de que ya te metiste a construir cosas reales.

Qué te vas a llevar

• Cómo pasar de “no sirve” a un diagnóstico con pasos claros.
• Un workflow de debug que funciona en proyectos chiquitos y también cuando huele a production.
• Cómo usar logs, breakpoints, Git y pruebas mínimas sin volverte loco.
• Qué hacer cuando “solo falla en mi compu” o “solo falla en producción”.
• Errores clásicos (y cómo salir de ellos) sin perder la tarde.

Por qué romperse es parte del build

Tu app no se rompe por maldad del universo (aunque a veces se siente personal). Se rompe porque:

• Estás pegando piezas: dependencias, versiones, APIs, DB, auth, UI… y cada combinación es un boleto de lotería.
• El entorno cambia: actualizaste Node/Python, se movió el .env, se regeneró el lockfile, el hosting cambió una variable, el certificado expiró.
• Ya entraron datos reales (aunque sean de 3 compas): los mocks siempre son bien portados; los usuarios no.

La diferencia entre alguien n00b y alguien que ya trae colmillo no es que nunca se le caiga nada. Es que cuando truena, no entra en pánico: sigue un proceso, arregla, aprende y no vuelve a pisar el mismo bug en la siguiente entrega.

Escenas muy reales:

1. Estás en el coworking con Wi‑Fi que se muere cada 20 minutos. Tu app “se cae” y juras que es tu código. Resulta que tu request se queda colgada porque la red está en modo zombie. Tu bug era el mundo.

2. El cliente de la PyME quiere ver su panel “en corto” antes de irse a comer. Haces deploy con prisa, sin revisar variables de entorno, y en production apuntas a la DB de staging. Ese susto lo vive más banda de la que admite.

Debug sin drama (pero con método)

1) Congela el momento: ¿qué cambió?

Antes de picarle a todo “a ver si con esto”, respóndete:

• ¿Qué fue lo último que viste funcionar?
• ¿Cambiaste código, dependencias, configuración, datos o solo reiniciaste?
• ¿Se rompió después de git pull, npm install, pip install, update del sistema o mover archivos?

Acción rápida:

• Revisa git status y git diff.
• En Node: ¿cambió package-lock.json / pnpm-lock.yaml?
• En Python: ¿se movió requirements.txt o tu lock (Poetry/Pipenv)?

Si no puedes decir “qué cambió”, tu primera chamba es recuperar esa pista.

2) Reduce el bug a algo reproducible (tu arma secreta)

“Truena a veces” no se arregla. Se arregla cuando lo haces fallar a voluntad.

Arma un mini guion:

• Paso 1: Abro la app
• Paso 2: Login con usuario X
• Paso 3: Voy a /perfil
• Resultado: 500 + pantalla blanca

Si lo reduces a 3–5 pasos, ya tienes medio fix.

Tip de guerra: si depende de datos, crea un registro controlado (usuario de prueba, item con nombre raro, etc.). En México los datos vienen con acentos, ñ, espacios dobles, teléfonos con +52, y el clásico “S/N”. Úsalos como stress test.

3) Lee el error como dev, no como víctima

Un stack trace asusta… hasta que aprendes a sacarle jugo.

Qué buscar:

• La primera línea útil: tipo de error (TypeError, KeyError, NullPointer, SQLSTATE, etc.).
• Tu código: el primer archivo que sea tuyo (no el de node_modules).
• Contexto: qué variable era undefined/null, qué query falló, qué endpoint regresó 401.

Si el error no dice nada, no es “misterio”: te faltan logs o te estás tragando la excepción.

4) Instrumenta con logs (sin ensuciar todo)

Logs no son “print por desesperación”. Son tu caja negra.

Regla práctica: loguea antes del punto de falla y loguea lo que te ayuda a decidir.

Node/Express

console.log("[login] body:", req.body);
console.log("[login] user found:", Boolean(user), user?.id);

Python (FastAPI/Django)

import logging
logger = logging.getLogger(__name__)

logger.info("[payment] payload_keys=%s", list(payload.keys()))
logger.info("[payment] user_id=%s", user_id)

No loguees: passwords, tokens completos, tarjetas, datos sensibles. Si necesitas identificar algo, mascara:

const mask = (t) => (t ? t.slice(0, 6) + "..." + t.slice(-4) : null);
console.log("token:", mask(token));

Esto también es seguridad: un log mal puesto es fuga de datos lista para que alguien la explote.

5) Aísla: ¿frontend, backend, red o datos?

Cuando algo “no jala”, casi siempre cae en una de estas:

• Frontend: error de JS, estado mal manejado, CORS, build roto.
• Backend: endpoint explota, auth, validación, excepción sin manejar.
• Red: DNS, timeout, Wi‑Fi, proxy, firewall, rate limits.
• Datos: esquema, migraciones, valores raros, encoding.

Acción rápida: abre DevTools → Network.

• ¿La request sí sale?
• ¿Regresa 200/400/401/500?
• ¿Se tarda demasiado?
• ¿Qué trae el body?

Esto te evita pasar dos horas peleándote con la UI cuando el problema era un 401 por token expirado.

6) Usa Git para volver a una versión sana (sin perder el avance)

Si ya estás atorado, regresa a un punto que sabes que funcionaba para confirmar si el bug está en tus cambios.

• git log --oneline para ubicar el commit “bueno”.
• Prueba con git checkout <commit> (solo para validar) o crea una rama.
• Alternativa menos agresiva: git stash tus cambios y corre.

La idea: comprobar si el bug lo metiste tú o lo metió el entorno.

7) Hipótesis + experimento corto

Debug es ciencia con deadline.

• Hipótesis: “El user viene null porque el query no encuentra por email con mayúsculas.”
• Experimento: loguea email, normaliza .toLowerCase(), prueba con el mismo usuario.
• Resultado: confirmas o descartas.

Evita el modo “cambio 20 cosas y a ver cuál pega”. Eso crea bugs nuevos y luego no sabes ni qué arregló qué.

8) Arregla… y luego evita que regrese

El fix real no es “ya jaló”. Es que no se vuelva a romper igual el próximo deploy.

Opciones anti-regresión (elige según el tiempo que traes):

• Un test mínimo para ese bug.
• Una validación (schema) con error claro.
• Un log con nivel warning/error.
• Un check en CI (lint/build/tests).
• Un README con setup exacto.

Si el bug te costó 3 horas, invertir 15 minutos en prevenirlo sale baratísimo.

Screenshots sugeridos (para que tu post-mortem no sea puro texto)

1. Captura del stack trace donde se ve el primer archivo de tu proyecto.
2. DevTools → Network con el request fallando (status y response).
3. Pantalla de variables de entorno en tu hosting (sin mostrar secretos).
4. git diff mostrando el cambio que rompió.
5. Log en consola con una línea clave (ej. user_id, payload_keys).

Errores comunes (y cómo salir rápido)

“En mi máquina sí funciona”

Causa típica: versiones distintas (Node/Python), .env diferente, DB distinta.

Solución:

• Imprime versiones: node -v, python --version.
• Asegura .env.example y revisa que existan variables.
• Si puedes, usa un manager: nvm, pyenv.

“Se rompió después de instalar dependencias”

Causa típica: lockfile cambió, dependencia major se actualizó.

Solución:

• No borres el lockfile “porque sí”.
• Reinstala limpio:
  • Node: borra node_modules y reinstala con el lock.
  • Python: recrea venv y fija versiones.

“500 en producción pero local no”

Causa típica: variables de entorno, migraciones, permisos o datos reales.

Solución:

• Revisa logs de production (Railway/Render/Fly/CloudWatch/etc.).
• Verifica migraciones corridas.
• Confirma permisos de storage/cache.

“Pantalla blanca en frontend”

Causa típica: excepción no capturada o build roto.

Solución:

• Abre la consola del navegador.
• Agrega un error boundary / manejo de error.
• En dev, asegúrate de tener sourcemaps.

“Funcionaba y de repente ya no: puro timeout”

Causa típica: red, API externa lenta, query sin índice.

Solución:

• Agrega timeouts y retries controlados.
• Mide tiempos (log de duración por request).
• Si es DB: revisa query y mete índice donde duele.

Checklist final (para salir del hoyo con dignidad)

• Identifiqué qué cambió (código/deps/config/datos).
• Tengo pasos para reproducir (3–5 pasos).
• Encontré el primer stack frame en mi código.
• Agregué logs útiles (sin filtrar secretos).
• Aislé capa: frontend/backend/red/datos.
• Verifiqué versiones y variables de entorno.
• Hice un fix con una hipótesis validada.
• Dejé una prevención mínima (test/validación/log/README).
• Si era grave: anoté mini post-mortem (qué pasó + cómo evitarlo).

FAQ

1) ¿Cuándo uso logs y cuándo uso debugger con breakpoints?

Logs cuando necesitas contexto continuo (requests, payloads, tiempos, producción). Breakpoints cuando quieres inspección paso a paso en local. En bugs de prod, casi siempre empiezas con logs.

2) ¿Qué hago si el error “no dice nada”?

Súbele a la observabilidad: agrega logs antes/después del punto sospechoso, captura excepciones con mensaje y contexto, y revisa que no tengas un catch silencioso tragándose todo.

3) ¿Cómo sé si el bug es mío o de una dependencia?

Aísla con Git (vuelve a un commit sano) y revisa cambios en el lockfile. Si el mismo código se rompe tras reinstalar deps, suena a versión/dep. Si solo se rompe con tu cambio, es tuyo (y eso es buena noticia: se arregla).

4) ¿Vale la pena escribir tests desde el principio si apenas estoy aprendiendo?

Sí, pero chiquito: un test para el bug que te acaba de doler es la mejor inversión. No necesitas 200 tests. Necesitas 1–3 que te eviten volver a caer.

5) ¿Qué hago si ya no tengo tiempo y necesito que “solo funcione” para la demo?

Haz un fix de emergencia sabiendo que es deuda técnica: feature flag, rollback, apagar temporalmente la parte rota o usar datos mock. Pero deja nota y tarea; si no, ese parche te revienta en la siguiente entrega.

Siguiente episodio: teaser

La app ya no se cae… pero tu código empieza a verse como plato de espagueti.

Siguiente paso del origen: cómo organizar tu proyecto sin matar tu velocidad (y sin que Git te odie).