ValidationException: 잘못된 UpdateExpression

TL;DR — 귀하의 UpdateExpression 형식이 잘못되었습니다. 10번 중 9번은 직접 사용되는 예약된 키워드(예: status, name, size)입니다. ExpressionAttributeNames에서 #placeholder로 바꾸세요. 메시지에는 정확한 토큰 이름이 표시됩니다.

무엇을 의미하는가

일반적인 메시지:

ValidationException: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: status
ValidationException: Invalid UpdateExpression: Syntax error; token: "=", near: "SET status ="
ValidationException: Invalid UpdateExpression: An expression attribute value used in expression is not defined; attribute value: :s

DynamoDB는 표현식 문자열을 구문 분석하고 유효한 문법이 아니거나 정의되지 않은 자리 표시자를 참조하는 모든 항목을 거부합니다.

왜 발생하는가

예약된 키워드는 raw로 사용됩니다. DynamoDB에는 hundreds of reserved words — status, name, size, count, data, year가 있습니다. 표현식에 직접 사용하면 구문 오류가 발생합니다. reserved words checker은 전체 목록에 대해 속성 이름을 테스트하고 앨리어스 맵을 내보냅니다.
귀하가 참조한 #name에 대한 ExpressionAttributeNames 항목이 누락되었습니다.
귀하가 참조한 :value에 대한 ExpressionAttributeValues 항목이 누락되었습니다.
잘못된 동사 문법 — 절을 잘못 혼합했거나(SET, REMOVE, ADD, DELETE 각각 고유한 구문을 가짐) 또는 잘못된 =.
특수 문자가 포함된 속성 이름(점, 대시)이 자리 표시자 없이 사용되었습니다.

어떻게 해결하는가

ExpressionAttributeNames(#status)까지 모든 속성 이름에 별칭을 지정합니다 - 예약어 목록을 완전히 우회하므로 모든 항목에 별칭을 지정하는 것이 안전한 습관입니다.
ExpressionAttributeValues에서 참조하는 모든 :value을 정의합니다.
올바른 절을 사용하세요. SET는 쓰기/덮어쓰기, REMOVE는 속성 삭제, ADD는 원자 번호/세트 증분, DELETE는 세트에서 제거입니다.
배송하기 전에 예약어 확인을 실행하세요. 속성 이름을 reserved words checker에 붙여넣으세요. 그러면 AWS 목록의 모든 이름에 플래그가 지정되고 필요한 #alias 지도가 인쇄됩니다.
식을 한 번만 작성하면 어디든 복사할 수 있습니다. 손으로 편집한 문자열이 표류합니다. 자리 표시자가 쌍을 유지하도록 하나의 소스에서 전체 UpdateExpression와 두 속성 맵을 모두 생성합니다.

예제

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, UpdateCommand} from '@aws-sdk/lib-dynamodb';

const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));

await doc.send(
  new UpdateCommand({
    TableName: 'Orders',
    Key: {pk: 'ORDER#1'},
    // #status aliases the reserved word "status"
    UpdateExpression: 'SET #status = :s, updatedAt = :t',
    ExpressionAttributeNames: {'#status': 'status'},
    ExpressionAttributeValues: {':s': 'SHIPPED', ':t': Date.now()}
  })
);

먼저 DynoTable에서 확인

앱 업데이트가 실패하면 프로덕션 코드를 변경하기 전에 DynoTable에서 이를 재현하십시오. ⌘K로 테이블을 열고 항목을 선택한 다음 인라인 업데이트 편집기를 사용합니다. DynoTable은 예약된 속성 이름을 자동으로 별칭으로 지정하고 두 속성 맵과 함께 생성된 UpdateExpression을 표시합니다. 스테이징(⌘S)을 사용하면 커밋하기 전에 편집 내용을 미리 보고 구문 오류를 찾아낼 수 있습니다.

일괄 수정의 경우 실패한 표현식을 Expression Builder에 붙여넣고 해당 출력을 SDK가 보내는 것과 비교하세요. 프로필 전환(⌘P)은 오류와 동일한 계정에서 테스트 실행을 유지합니다. 설정 → 프로필에서 연결 테스트를 사용하여 프로필이 일치하는지 확인하세요. 프로필 설정은 Connect to AWS 및 Install를 참조하세요. 오류가 status 또는 data와 같은 특정 토큰의 이름을 지정하는 경우 reserved words checker의 속성 이름을 교차 확인하세요. 예약된 속성뿐만 아니라 모든 속성 이름에 별칭을 지정하는 것은 이러한 종류의 오류를 완전히 방지하는 안전한 습관입니다.

출처

Using update expressions in DynamoDB (2026-07-13 인증)
Reserved words in DynamoDB (2026-07-13 인증)

참고 자료

위에 링크된 공식 AWS 문서를 기준으로 2026년 7월 13일에 마지막으로 확인되었습니다.