Errores de zona horaria y DST: una lista de verificación para una programación fiable

Qué se rompe en la programación cuando cambian las zonas horarias

Cuando la programación falla, los usuarios no piensan “zonas horarias”. Piensan que la app es poco fiable. El mismo evento aparece a la hora equivocada, los recordatorios llegan antes o después, o una reunión se pierde porque se desplazó sin avisar.

Los fallos más confusos son los que parecen correctos en el código. Guardas una fecha, la muestras, y las pruebas pasan. Luego un calendario real cruza una frontera de zona horaria y tu “conversión simple” se vuelve un objetivo móvil. Ahí está el corazón de los errores de zona horaria y DST: los offsets cambian, pero tu valor almacenado o tu conversión asumen que no cambian.

La rotura suele aparecer en momentos previsibles:

• Inicio de DST (la “hora que falta”): una hora local como 02:30 puede no existir.
• Fin de DST (la “hora doble”): 01:30 puede ocurrir dos veces y se elige la equivocada.
• Viajes (o trabajo remoto): el mismo usuario abre la app en otra zona.
• Movimiento del servidor o valores por defecto de contenedor: producción corre en una zona distinta a tu portátil.
• Backfills e importaciones: datos de terceros llegan con un offset, no con una zona real.

Un ejemplo rápido: un usuario programa “todos los días a las 9:00 AM” mientras está en New York. Si lo guardas como “09:00 menos el offset actual” (en vez de “9:00 en America/New_York”), puede convertirse en 8:00 AM tras el cambio de DST aunque el usuario no lo pidió.

Unas pocas reglas evitan la mayoría de problemas:

• Decide si la programación está ligada a un lugar (una zona horaria) o a un instante (UTC).
• Almacena UTC para momentos concretos y guarda la zona IANA para horarios locales repetidos.
• Trata los “horarios de reloj” durante las transiciones DST como casos especiales, no como conversiones normales.
• Añade pruebas para inicio de DST, fin de DST y cambio de zona del usuario.

Vocabulario rápido: UTC, hora local, offsets y zonas

Los errores de programación suelen empezar porque la gente confunde palabras que suenan similares. Trátalas como conceptos separados y nómbralas claramente en tu código y UI.

UTC (Coordinated Universal Time) es un reloj global único. No cambia por horario de verano. Un instante como "2026-01-16T14:30:00Z" es inequívoco en cualquier parte del mundo.

Hora local es lo que una persona ve en su reloj. “9:00 AM” solo tiene sentido cuando también sabes dónde (y a veces cuándo) ocurre.

Una división útil es:

• Instante: un momento específico en el tiempo (bueno para logs, pagos, recordatorios).
• Tiempo de calendario: una fecha y una hora de reloj como “Lunes a las 9:00 AM” (bueno para planes humanos).
• Zona horaria: las reglas que convierten un instante en hora local.

Un offset es solo un número como UTC-5. Te dice la diferencia respecto a UTC ahora mismo, pero no incluye cambios futuros o pasados por reglas de DST.

Una zona nombrada (zona IANA) es una etiqueta como “America/New_York”. Incluye el conjunto completo de reglas, incluyendo cuándo empieza y acaba el DST.

Los eventos recurrentes son el caso especial que suele confundir a los equipos. “Cada martes a las 9:00 AM en París” normalmente debería permanecer a las 9:00 AM hora de París, aunque el instante UTC correspondiente cambie cuando el DST se mueva.

Qué almacenar en la base de datos (y qué no)

Muchos errores de zona horaria y DST empiezan por un modelo de datos incorrecto. Si guardas la “versión para mostrar” de la hora (como una cadena formateada o un offset crudo), pierdes la información necesaria para tomar decisiones correctas después.

Cuando un evento es un momento específico en el tiempo (un webinar que empieza en un instante exacto mundialmente), guárdalo como un instante en UTC. Normalmente eso significa timestamps como starts_at_utc y ends_at_utc.

Cuando un evento debe seguir reglas locales (como “todos los lunes a las 9:00 AM en New York”), guarda el ID de la zona, no solo el offset. Usa un nombre de zona IANA como America/New_York, porque los offsets cambian con DST y a veces cambian por ley.

También ayuda guardar la fecha y hora local original que escribió la persona. Eso preserva la intención y hace que las ediciones sean previsibles. Por ejemplo, si alguien eligió “2026-03-08 09:00” en America/Los_Angeles, quieres recordar esa elección local aunque el instante UTC correspondiente se mueva alrededor de los límites de DST.

Un conjunto práctico de campos a considerar:

• zone_id (nombre IANA) para cualquier programación ligada a un lugar
• local_date y local_time para la hora de reloj que el usuario pretende
• starts_at_utc (y ends_at_utc) cuando el evento es un instante fijo
• created_offset_minutes (opcional) para auditoría/depuración, no como fuente de verdad
• timezone_version o una marca de “rules updated at” (opcional) si tu plataforma lo soporta

Evita almacenar solo un offset como -0500, especialmente para eventos futuros. No puede decirte qué conjunto de reglas DST aplicar, y estará equivocado parte del año.

Para depuración, registra tres cosas juntas: el ID de zona, el offset en el momento de creación y el instante UTC calculado. Sin las tres, los reportes de “se movió una hora” a menudo se convierten en adivinanzas.

Elige el modelo correcto para cada tipo de programación

La mayoría de errores en programación son un desajuste: guardas un tipo de tiempo, pero los usuarios esperan otro. Antes de escribir código, decide qué modelo estás construyendo.

Modelo 1: Instante fijo (un único momento real)

Usa esto cuando el evento debe ocurrir en el mismo momento en todo el mundo. Guárdalo como un instante (timestamp UTC) y conserva la zona solo para mostrar.

Un vuelo que sale el 2026-03-10 14:00 desde JFK es un instante fijo. Si un viajero lo ve en Londres, la hora del reloj cambia, pero el momento no.

Modelo 2: Hora local flotante (misma hora de reloj en un lugar)

Usa esto cuando el evento está ligado a un reloj local, no a un momento global. Guarda la fecha local, la hora local y la zona IANA (como “America/New_York”). Luego resuelve a un instante cuando necesites programar trabajos o enviar recordatorios.

Una alarma diaria a las 07:00 es hora local flotante. La gente espera que permanezca a las 07:00 aun cuando comience o termine el DST.

Si no estás seguro de qué modelo encaja, pregúntate:

• ¿Debe el evento ocurrir al mismo instante para todo el mundo?
• ¿O debe ocurrir a la misma hora del reloj local en un lugar?
• Si un usuario cambia la zona horaria de su dispositivo, ¿debería moverse el evento?
• Cuando cambia el DST, ¿debe mantenerse la hora del reloj o el instante?

Para invitaciones entre zonas, guarda la intención del organizador. Si el organizador eligió “9:00 AM hora de New York”, guarda esa zona y hora local. Cada asistente puede verlo en su propia zona, pero la regla fuente queda clara.

Escribe la regla en comentarios de código y usa nombres claros. Por ejemplo: startsAtUtc para instantes fijos, o localStartTime + timeZoneId para programaciones flotantes. Esa decisión única evita ediciones “útiles” futuras que reintroduzcan sorpresas por DST.

Mostrar la hora local sin sorprender a la gente

Muchos errores de zona horaria y DST aparecen en la interfaz, no en la base de datos. Un valor por defecto seguro es: mantén UTC (o un instante) en tu app y convierte a la zona del visualizador en el último momento, justo antes de mostrar.

Ese “último momento” importa. Si conviertes antes (por ejemplo, en la respuesta de la API o dentro de la lógica de negocio), es fácil convertir dos veces después o formatear de manera diferente en distintas pantallas. Elige un solo lugar donde ocurra el formateo de presentación (a menudo el frontend) y reutiliza el mismo formateador para que un evento luzca idéntico en vistas de lista, páginas de detalle, emails y notificaciones.

Cuando hay riesgo de confusión, muestra la zona. Un simple “9:00 AM” está bien para un recordatorio personal, pero es arriesgado para programaciones compartidas. Usa formatos como “9:00 AM PT” o “9:00 AM (America/Los_Angeles)” en invitaciones, paneles de administración y cualquier cosa entre equipos. Las abreviaturas pueden ser ambiguas (CST puede significar cosas distintas), así que usa el nombre completo de la zona cuando haya mucho en juego.

Si un usuario no tiene zona guardada, por defecto usa la zona del dispositivo, pero hazla visible y fácil de cambiar. La gente viaja. Existen equipos remotos. “Mi dispositivo lo adivinó mal” es un ticket de soporte real.

Los horarios ambiguos durante el retroceso necesitan cuidado especial. “1:30 AM” ocurre dos veces cuando los relojes se atrasan. Si un usuario está eligiendo una hora en esa fecha, adviértele y ofrece una elección clara, como “1:30 AM (antes del cambio de reloj)” vs “1:30 AM (después)”, o muestra el offset UTC.

Manejar saltos de DST y horas ambiguas

El horario de verano es donde muchos sistemas de programación quedan al descubierto. La parte complicada es que el cambio del reloj puede hacer que una hora local sea imposible o poco clara, aunque a una persona le parezca normal.

En el avance de primavera, se salta una hora. En muchos lugares, 2:30 AM simplemente no existe ese día. Si un usuario elige una hora inexistente, la app debe hacer algo explícito en vez de crear silenciosamente un timestamp equivocado.

En el retroceso de otoño, una hora se repite. Una hora como 1:30 AM ocurre dos veces, una antes de atrasar el reloj y otra después. Eso hace que la hora local sea ambigua a menos que también sepas cuál ocurrencia quiso el usuario.

Una política que se mantenga consistente

Elige una política y aplícala en todas partes (creación, edición, importación, API).

• Para tiempos inexistentes (spring): desplaza hacia adelante a la siguiente hora válida, o bloquea y pide al usuario que elija.
• Para tiempos repetidos (fall): elige la primera ocurrencia (más temprana) o la segunda (más tardía), o pregunta cuando importe (pagos, plazos).
• Si resuelves automáticamente, muestra una pequeña confirmación como “Ajustado a 3:00 AM debido al DST.”
• Siempre guarda el nombre de la zona del usuario (como America/New_York), no solo un offset.
• Registra la elección de resolución para que el mismo evento no cambie después.

Después de decidir, persiste lo que elegiste. Por ejemplo, almacena “prefer_earlier” vs “prefer_later” para ese evento (algunas librerías llaman a esto una bandera de fold). Sin eso, un usuario que edite el evento meses después podría ver que la hora se desplaza o cambia a la otra ocurrencia.

Ejemplo: alguien programa “3 de nov, 1:30 AM” en New York. Si tu app siempre elige la primera 1:30 AM, mantén esa decisión ligada al evento. Si más tarde recalculas desde cero, podría pasar a la segunda 1:30 AM y mover la reunión una hora.

Paso a paso: construir un flujo de programación que resista DST

Las funciones de programación fallan cuando mezclan dos ideas distintas: un momento fijo en el tiempo (un instante) y una hora de “reloj de pared” que la gente espera localmente. Un flujo fiable empieza eligiendo el modelo y luego capturando suficiente información para recrear lo que el usuario quiso meses después.

Un flujo de programación seguro para DST

• Clasifica el evento: instante fijo (un único momento) o hora local flotante (anclada al reloj de una zona).
• Cuando el usuario elige una hora, guarda la fecha/hora local más el ID completo de zona (por ejemplo, America/New_York), no solo un offset como -05:00.
• Antes de guardar, valida la hora local contra las reglas de la zona: maneja huecos de DST (una hora que no existe) y solapes (una hora que ocurre dos veces) usando tu política elegida.
• Persiste el timestamp UTC para el momento real de ejecución, y conserva el ID de zona y los campos locales originales cuando necesites mostrar “qué eligió el usuario.”
• Al mostrar, convierte desde UTC a la zona del visualizador, y añade la etiqueta cuando importe (por ejemplo, “10:00 AM hora de New York”).

La regla que debes elegir

Durante un hueco de spring-forward, ¿rechazas la hora y pides al usuario que elija de nuevo, o la mueves automáticamente al siguiente minuto válido? Durante un solape de fall-back, ¿eliges la ocurrencia temprana, la tardía o preguntas? Escoge un comportamiento, escríbelo en lenguaje claro y mantenlo consistente en crear, editar y reenviar flujos.

Errores comunes que causan bugs de DST y zona horaria

Estos errores suelen empezar pequeños: un atajo en el manejo de fechas que parece inofensivo hasta que un usuario topa con un cambio de DST o abre la app desde otra región.

Los fallos que aparecen con más frecuencia:

• Almacenar la hora local sin la información de zona. Guardar 2026-03-08 09:00 sin también guardar la zona IANA (como America/New_York) te obliga a adivinar después.
• Usar accidentalmente la zona horaria del servidor. “Parsea una fecha, crea un objeto Date, guárdalo” puede funcionar en desarrollo y moverse en producción si la zona del servidor/contenedor es distinta.
• Sumar 24 horas para significar “mañana”. now + 24h no es lo mismo que “la misma hora local mañana” durante cambios de DST.
• Asumir que los offsets no cambian. La gente hardcodea -0500 y continúa. Los offsets son resultado de reglas de la zona, no la identidad de la zona, y las reglas pueden cambiar.
• Parsear cadenas de tiempo que dependen de locale o de peculiaridades del navegador. Entradas como 03/04/2026 9:00 pueden significar fechas distintas según la configuración, y algunos navegadores aceptan formatos que otros rechazan.

Un fallo común: un usuario programa “9:00 AM todos los lunes” en New York. Si solo guardas un offset (UTC-5) en vez de la zona, el evento se desplazará una hora después de que empiece el DST, aunque el usuario espere que siga a las 9:00 AM.

Cómo escribir pruebas que no fallen dos veces al año

Los errores de zona horaria y DST suelen aparecer solo en marzo y noviembre (o finales de marzo y finales de octubre en Europa). La solución no es “más pruebas”. Esas pruebas correctas, ejecutadas de la misma forma en todas partes.

Haz el tiempo determinista

Elimina dependencias ocultas. En cada prueba, congela el reloj y establece una zona explícita. No confíes en el portátil del desarrollador, el runner de CI o valores por defecto del contenedor.

Un hábito simple: construye fechas de prueba desde instantes UTC conocidos y declara siempre la zona a la que conviertes.

Cubre las fechas complicadas a propósito

Elige al menos una zona de EE. UU. y una de la UE y prueba tanto el salto de primavera (hora faltante) como la superposición de otoño (hora repetida). Luego añade casos que se olvidan a menudo:

• Hora local inválida (gap de spring): una hora local que no existe
• Hora local ambigua (overlap de fall): la misma hora de reloj mapeando a dos instantes
• Eventos recurrentes que cruzan el límite: genera 8–12 semanas y verifica cada ocurrencia
• Instantáneas de formateo UI: verifica cadenas renderizadas bajo distintos locales y zonas

Por ejemplo, prueba una reunión semanal fijada a 09:30 en America/New_York. Cuando empieza el DST, la hora UTC cambiará pero la hora local debe seguir siendo 09:30. Cuando termina el DST, asegúrate de que 01:30 se maneje con tu regla elegida (primera instancia vs segunda) y que la regla quede afirmada en las pruebas.

Incluye al menos una prueba end-to-end realista que cree, almacene y vuelva a renderizar el evento. Eso detecta desajustes entre almacenamiento en BD, serialización de la API y formateo UI.

Escenario ejemplo: reunión semanal a través de DST para un equipo remoto

Un manager en New York programa una reunión semanal: todos los lunes a las 9:00 AM. Asistentes están en London y Phoenix. Todos esperan que la reunión se mantenga a las 9:00 AM hora de New York, incluso cuando los relojes cambien.

Esto es lo que hace la lógica ingenua: la app guarda la primera ocurrencia como un timestamp UTC (por ejemplo 14:00 UTC) y luego la repite sumando 7 días en UTC. Eso parece bien hasta que cambia el DST.

• Spring forward: New York pasa de UTC-5 a UTC-4. Si sigues repitiendo 14:00 UTC, la reunión se convierte en 10:00 AM en New York.
• Fall back: New York pasa de UTC-4 a UTC-5. Repetir el mismo UTC hace que la reunión aparezca a las 8:00 AM localmente.

El comportamiento correcto empieza por guardar la zona y la regla, no solo un timestamp. Para una reunión semanal, guarda algo como: zone = America/New_York, weekday = Monday, local time = 09:00, frequency = weekly. Entonces cada ocurrencia se calcula para esa zona y se convierte a UTC solo para entrega (invitaciones de calendario, recordatorios, payloads de API).

London la verá desplazarse una hora durante las semanas en que EE. UU. y Reino Unido cambian el DST en fechas distintas. Phoenix (sin DST) también puede ver cambios. Eso es esperado cuando la regla es “9:00 AM hora de New York”.

Un texto visible al usuario evita confusiones. Muestra la zona cuando importe y confirma la regla en palabras sencillas:

• Visualización: “Lun 9:00 AM (hora de New York)”
• Confirmación: “Se repite todos los lunes a las 9:00 AM America/New_York. Las horas pueden diferir para compañeros en otras zonas cuando cambie el horario de verano.”

Lista rápida antes de lanzar una función de programación

Los errores de zona horaria y DST suelen aparecer tras el lanzamiento, cuando usuarios reales cruzan fronteras o cambian los relojes. Una verificación rápida previa al envío puede ahorrar semanas de soporte y muchos reportes de “mi recordatorio sonó a la hora equivocada.”

Comprobaciones del modelo de datos

Para cada cosa programada, deberías poder responder a una pregunta: ¿es esto un instante fijo, o sigue las reglas locales del reloj?

• Instantes fijos (recordatorios puntuales, timestamps de logs): almacena como timestamps UTC.
• Eventos recurrentes de “hora local” (cada lunes a las 9:00 en Berlín): almacena los campos de hora local más el ID de zona IANA (por ejemplo, Europe/Berlin), no solo un offset.
• Nunca trates un offset numérico (como -05:00) como una zona horaria.

Comprobaciones de DST y usuario

Haz de los casos extremos de DST una parte principal del comportamiento del producto.

• Cuando un usuario elige una hora local, detecta y maneja horas inválidas (gap de spring) y horas ambiguas (overlap de fall). Decide: bloquear, ajustar automáticamente o preguntar.
• Pruebas: congela “ahora” y establece una zona explícita en cada prueba. Incluye al menos un caso de inicio y uno de fin de DST.
• UI y notificaciones: muestra la zona cuando importe, especialmente en emails, invitaciones de calendario y recordatorios.

Próximos pasos: arreglar bugs existentes de programación sin reescribir todo

Si tu función de programación ya está en producción, arreglar bugs de zona horaria y DST es principalmente obtener visibilidad primero y luego apretar una capa a la vez. No necesitas una reescritura grande para detener la hemorragia.

Empieza con una auditoría rápida de datos. Busca campos que mezclen conceptos, como una columna llamada start_time que a veces guarda UTC, a veces hora local, o cadenas como “2026-01-16 09:00” sin zona. También revisa campos duplicados (utc_time y local_time) donde nadie recuerda cuál es la fuente de verdad.

Añade logging ligero alrededor de cada conversión. Cuando un usuario reporte “se movió una hora”, querrás evidencia de qué decidió el sistema:

• Loggea la zona IANA del usuario (como America/New_York), no solo un offset.
• Loggea el offset usado en ese instante (por conciencia DST).
• Loggea el valor de entrada y el resultado UTC calculado.
• Loggea la ruta de renderizado (valor UTC almacenado -> visualización local).

Luego arregla en un orden que reduzca el dolor de usuarios rápidamente: primero renderizado y pantallas de confirmación, luego reglas de almacenamiento, y después la lógica de recurrencia.

Si heredaste un código generado por IA, asume que el manejo del tiempo es inconsistente en archivos y endpoints. Conversiones ocultas, valores por defecto de librerías y pruebas que solo pasan fuera de semanas DST son comunes.

Si necesitas una segunda revisión rápida, FixMyMess (fixmymess.ai) está diseñada para diagnosticar y reparar código generado por IA, incluida la lógica de programación que falla alrededor del DST. Una auditoría corta suele bastar para señalar dónde se mezclaron offsets, zonas y conversiones.