DynamoDB TTL attribute must be a Number

TL;DR — El Time to Live de DynamoDB solo borra un Item cuando su atributo TTL designado contiene un Number que representa una marca de tiempo de época Unix en segundos. Una cadena como "1735689600", un valor en milisegundos, una fecha ISO-8601, o un atributo ausente se ignoran silenciosamente — el Item nunca expira. Almacena el TTL como un Number en segundos de época y reescribe los Items afectados.

Qué significa

# A second UpdateTimeToLive call within one hour of the first raises:
ValidationException  (TTL settings can only be modified once per table per hour)

# The quieter failure — no error at all, item just never expires:
TTL attribute "expiresAt" = "2026-01-01T00:00:00Z"   ← String, ignored
TTL attribute "expiresAt" = 1735689600000            ← milliseconds: tens of thousands of years away

Habilitar el TTL (UpdateTimeToLive) tiene éxito incluso cuando el atributo aún no existe o es de un tipo incorrecto — DynamoDB no comprueba el tipo de entrada. El fallo aparece más tarde: el proceso de TTL en segundo plano solo borra un Item cuando el atributo es un Number que contiene una marca de tiempo de época Unix en segundos que está en el pasado (y no más de cinco años en el pasado). Cualquier otra cosa se trata como "sin expiración".

Por qué ocurre

Almacenado como cadena — el valor es {"S": "1735689600"} en lugar de {"N": "1735689600"}. El TTL ignora los tipos que no son N.
Milisegundos en lugar de segundos — Date.now() (JavaScript) devuelve milisegundos; un valor de 13 dígitos está a decenas de miles de años en el futuro, así que el Item efectivamente nunca expira.
Una cadena de fecha ISO-8601 / legible por humanos en lugar de segundos de época.
Una marca de tiempo de más de cinco años en el pasado — el proceso de TTL la ignora en lugar de borrar el Item.
Un nombre de atributo diferente del registrado con el TTL (el nombre distingue mayúsculas de minúsculas).
Llamar a UpdateTimeToLive de nuevo demasiado pronto — el cambio tarda hasta una hora en procesarse por completo, y cualquier llamada adicional a UpdateTimeToLive para la misma tabla durante esa hora lanza un ValidationException.

Cómo solucionarlo

Escribe el valor del TTL como un Number en segundos de época — Math.floor(Date.now() / 1000) + ttlSeconds en JavaScript, int(time.time()) + ttl en Python. Nunca almacenes milisegundos.
Usa el tipo N, no S. Con el cliente de bajo nivel es {"N": "1735689600"}; el Document Client marshaliza un número nativo por ti.
Haz coincidir el nombre del atributo registrado exactamente, incluidas mayúsculas y minúsculas. Confírmalo con DescribeTimeToLive.
Rellena los Items existentes — los Items escritos antes de la solución siguen llevando el valor incorrecto; reescríbelos con un Number correcto en segundos de época.
Espera una hora entre cambios de configuración del TTL — UpdateTimeToLive tarda hasta una hora en procesarse, y las llamadas posteriores durante esa ventana se rechazan con un ValidationException.

¿Quieres ver el tipo de transferencia de cada atributo mientras navegas por una tabla? La aplicación de escritorio DynoTable renderiza las etiquetas de tipo N/S/M en línea, así que un TTL almacenado como cadena salta a la vista antes de que te cueste un Item sin expirar.

FAQ

¿Por qué mi TTL de DynamoDB no está borrando Items? El atributo TTL debe ser un Number que contenga una marca de tiempo de época Unix en segundos. Un valor de cadena, un valor en milisegundos, una fecha ISO, o un nombre que no coincida con el atributo TTL registrado se ignoran todos silenciosamente, así que el Item nunca expira. El borrado tampoco es inmediato — DynamoDB normalmente elimina los Items expirados en unos pocos días desde su hora de expiración.

¿DynamoDB valida el tipo del atributo TTL cuando habilito el TTL? No. UpdateTimeToLive tiene éxito incluso si el atributo falta o es de un tipo incorrecto. El requisito de tipo (Number, segundos de época) solo lo aplica el proceso de borrado en segundo plano, por eso un TTL incorrecto falla en silencio.

Errores relacionados

Float / decimal number types not supported — un escollo de tipado numérico relacionado.
ValidationException (visión general)
Aprende: DynamoDB TTL · DynamoDB data types

Referencias

Última verificación el 2026-07-13 con la documentación oficial de AWS enlazada arriba.