Attribute name is a reserved keyword

요약 — DynamoDB의 예약어 중 하나(약 570개가 있습니다 — status, name, size, type, data, year, count 등 많이)인 속성 이름을 표현식에서 직접 사용했습니다. ExpressionAttributeNames 플레이스홀더 — status에 매핑된 #status — 로 교체하면 요청이 통과합니다.

무엇을 의미하는가

ValidationException: 1 validation error detected: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: status
ValidationException: 1 validation error detected: Invalid KeyConditionExpression: Attribute name is a reserved keyword; reserved keyword: name

DynamoDB는 표현식(UpdateExpression, ConditionExpression, FilterExpression, KeyConditionExpression, ProjectionExpression)에 문자 그대로 나타날 수 없는 예약어 목록을 유지합니다. 속성이 그중 하나이면 파서가 표현식을 거부합니다. ValidationException(HTTP 400)이며 이름을 별칭하기 전까지 재시도할 수 없습니다. 메시지가 정확한 예약어를 지정합니다.

왜 발생하는가

흔한 속성 이름이 예약어와 충돌 — status, name, size, type, data, year, count, timestamp, source, region, 그리고 수백 개 더가 예약되어 있습니다.
예약된 속성 이름을 직접 나열하는 ProjectionExpression.
예약된 이름을 참조하는 FilterExpression/ConditionExpression(#status = :s는 작동하고 status = :s는 안 됨).
숫자로 시작하거나 공백, 점, 하이픈을 포함하는 속성 이름 — 이것들도 ExpressionAttributeNames 별칭이 필요하며 관련 검증 오류를 일으킵니다.

어떻게 해결하는가

ExpressionAttributeNames로 이름을 별칭하세요. #placeholder를 실제 이름에 매핑하고 표현식에서 플레이스홀더를 사용하세요:

await doc.send(
  new UpdateCommand({
    TableName: 'Orders',
    Key: {pk: 'ORDER#1'},
    UpdateExpression: 'SET #status = :s',
    ExpressionAttributeNames: {'#status': 'status'},
    ExpressionAttributeValues: {':s': 'shipped'}
  })
);

플레이스홀더는 #으로 시작하고 영숫자/밑줄이 뒤따라야 하며, 사용하는 모든 #name은 정의되어야 합니다(그리고 정의된 모든 것은 사용되어야 합니다).
방어적으로 별칭하세요 — 표현식의 모든 속성 이름을 별칭하면 어느 단어가 예약되었는지 알 필요가 전혀 없습니다.
리터럴 점을 포함하는 이름은 단일 플레이스홀더로 별칭하세요 — 문자 그대로 Safety.Warning이라는 이름의 속성은 전체 이름에 대한 별칭 하나({'#sw': 'Safety.Warning'})가 필요합니다. 별칭되지 않은 .은 문서 경로 구분자로 읽히기 때문입니다. 진짜 중첩 경로의 경우 대신 각 세그먼트를 별칭하세요(#pr.#5star).

FAQ

DynamoDB에서 "Attribute name is a reserved keyword"를 어떻게 고치나요? ExpressionAttributeNames로 속성을 별칭하세요. #status 같은 플레이스홀더를 실제 이름 "status"에 매핑하고 표현식에서 문자 그대로의 단어 대신 #status를 사용하세요. 플레이스홀더는 #으로 시작해야 하고 정의하는 모든 것은 사용되어야 합니다.

어떤 DynamoDB 속성 이름이 예약되어 있나요? status, name, size, type, data, year, count, timestamp, region 같은 일상적 이름을 포함해 약 570개의 예약어가 있습니다. 목록을 외우기보다 ExpressionAttributeNames로 표현식의 모든 속성 이름을 별칭하세요.

참고 자료

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

Attribute name is a reserved keyword

무엇을 의미하는가

왜 발생하는가

어떻게 해결하는가

FAQ

관련 오류

참고 자료