DynamoDB TTL attribute must be a Number

요약 — DynamoDB의 Time to Live는 지정된 TTL 속성이 초 단위 Unix 에포크 타임스탬프를 나타내는 Number를 지닐 때만 항목을 삭제합니다. "1735689600" 같은 문자열, 밀리초 값, ISO-8601 날짜, 또는 누락된 속성은 조용히 무시됩니다 — 항목이 절대 만료되지 않습니다. TTL을 에포크 초 Number로 저장하고 영향받은 항목을 다시 쓰세요.

무엇을 의미하는가

# 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

TTL 활성화(UpdateTimeToLive)는 속성이 아직 존재하지 않거나 잘못된 타입일 때도 성공합니다 — DynamoDB는 미리 타입을 확인하지 않습니다. 실패는 나중에 나타납니다: 백그라운드 TTL 프로세스는 속성이 과거의(그리고 5년 이내 과거의) 초 단위 Unix 에포크 타임스탬프를 지닌 Number일 때만 항목을 삭제합니다. 그 외의 모든 것은 "만료 없음"으로 취급됩니다.

왜 발생하는가

문자열로 저장됨 — 값이 {"N": "1735689600"} 대신 {"S": "1735689600"}. TTL은 N이 아닌 타입을 무시합니다.
초 대신 밀리초 — Date.now()(JavaScript)는 밀리초를 반환합니다. 13자리 값은 수만 년 미래이므로 항목이 사실상 절대 만료되지 않습니다.
에포크 초가 아닌 ISO-8601 / 사람이 읽는 날짜 문자열.
5년 넘게 과거의 타임스탬프 — TTL 프로세스가 항목을 삭제하는 대신 무시합니다.
TTL에 등록된 것과 다른 속성 이름(이름은 대소문자를 구분).
UpdateTimeToLive를 너무 빨리 다시 호출 — 변경이 완전히 처리되는 데 최대 한 시간이 걸리며, 그 시간 동안 같은 테이블에 대한 추가 UpdateTimeToLive 호출은 ValidationException을 발생시킵니다.

어떻게 해결하는가

TTL 값을 에포크 초의 Number로 쓰세요 — JavaScript에서 Math.floor(Date.now() / 1000) + ttlSeconds, Python에서 int(time.time()) + ttl. 절대 밀리초를 저장하지 마세요.
S가 아니라 N 타입을 사용하세요. 저수준 클라이언트에서는 {"N": "1735689600"}입니다. Document Client는 네이티브 숫자를 대신 마셜링합니다.
등록된 속성 이름을 대소문자를 포함해 정확히 일치시키세요. DescribeTimeToLive로 확인하세요.
기존 항목을 백필하세요 — 수정 전에 쓰인 항목은 여전히 잘못된 값을 지닙니다. 올바른 에포크 초 Number로 다시 쓰세요.
TTL 구성 변경 사이에 한 시간 기다리세요 — UpdateTimeToLive는 처리하는 데 최대 한 시간이 걸리며, 그 창 동안 추가 호출은 ValidationException으로 거부됩니다.

테이블을 탐색하는 동안 모든 속성의 와이어 타입을 보고 싶나요? DynoTable 데스크톱 앱은 N/S/M 타입 태그를 인라인으로 렌더링하므로, 문자열로 저장된 TTL이 만료되지 않은 항목의 비용을 치르기 전에 튀어나옵니다.

FAQ

내 DynamoDB TTL이 왜 항목을 삭제하지 않나요? TTL 속성은 초 단위 Unix 에포크 타임스탬프를 지닌 Number여야 합니다. 문자열 값, 밀리초 값, ISO 날짜, 또는 등록된 TTL 속성과 일치하지 않는 이름은 모두 조용히 무시되어 항목이 절대 만료되지 않습니다. 삭제도 즉각적이지 않습니다 — DynamoDB는 일반적으로 만료 시간의 며칠 이내에 만료된 항목을 제거합니다.

TTL을 활성화할 때 DynamoDB가 TTL 속성 타입을 검증하나요? 아니요. UpdateTimeToLive는 속성이 없거나 잘못된 타입이어도 성공합니다. 타입 요구 사항(Number, 에포크 초)은 백그라운드 삭제 프로세스에서만 강제되며, 그래서 잘못된 TTL이 조용히 실패합니다.

참고 자료

공식 AWS 문서(위 링크)를 기준으로 2026-07-13에 마지막으로 검증되었습니다.

DynamoDB TTL attribute must be a Number

무엇을 의미하는가

왜 발생하는가

어떻게 해결하는가

FAQ

관련 오류

참고 자료