ValidationException: ExpressionAttributeValues에 잘못된 값이 포함되어 있습니다.

TL;DR — ExpressionAttributeValues의 값이 비어 있거나, 지원되지 않는 유형이 있거나, 표현식에 사용된 :placeholder이 정의된 적이 없습니다. 모든 :value가 존재하고 비어 있지 않은지 확인하세요.

무엇을 의미하는가

일반적인 메시지:

ValidationException: ExpressionAttributeValues contains invalid value: One or more parameter values were invalid: An AttributeValue may not contain an empty string for key :s
ValidationException: Value provided in ExpressionAttributeValues unused in expressions: keys: {:x}
ValidationException: An expression attribute value used in expression is not defined; attribute value: :v

왜 발생하는가

빈 문자열/빈 바이너리 — 역사적으로 DynamoDB는 ""를 거부했습니다. 이제 키가 아닌 속성에 빈 문자열이 are 허용되지만(빈 목록/맵도 괜찮음) 키 속성과 빈 세트의 빈 값은 여전히 유효하지 않습니다.
정의되지 않은 자리 표시자 — 표현식이 :v을 참조하지만 ExpressionAttributeValues에는 :v이 없습니다.
사용되지 않은 자리 표시자 — :x를 정의했지만 이를 사용하는 표현식이 없습니다(DynamoDB가 전체 요청을 거부함).
잘못된 유형 — 원시 JS 객체/undefined/NaN 또는 (저수준 클라이언트의 경우) 잘못된 {S}/{N} 래퍼를 전달합니다.
ADD/DELETE 연산에 전달된 빈 집합 — 이러한 절은 집합(또는 ADD의 경우 숫자) 피연산자를 가지며 집합은 비어 있을 수 없습니다.

어떻게 해결하는가

식의 모든 :value는 ExpressionAttributeValues에서 정의되어야 하며 정의된 모든 값은 사용해야 합니다** — 두 값을 정확하게 동기화해야 합니다.
비어 있음/undefined에 대비하세요. 소스가 undefined일 때 :v를 전달하지 마세요. 대신 조항을 삭제하세요. 세트의 경우 구성원이 하나 이상 있는지 확인하세요.
Document Client(@aws-sdk/lib-dynamodb)를 사용하면 기본 JS 값이 마샬링되므로 대부분의 유형 래퍼 오류가 제거됩니다.
표현식 문자열에 대해 맵을 감사합니다. 호출 전에 두 가지를 나란히 인쇄합니다. 표현식의 모든 :token는 ExpressionAttributeValues의 키로 나타나야 하며 맵의 모든 키는 표현식에 나타나야 합니다.
낮은 수준 클라이언트의 경우 연결 유형을 확인합니다. 빈 세트 {SS: []} 또는 키 속성의 누락된 유형 래퍼는 자리 표시자가 정의된 경우에도 여전히 실패합니다.

예제

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

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

const email = getEmail(); // could be undefined
const names = {'#e': 'email'};
const values = {':e': email};

if (email == null) throw new Error('email required'); // don't send :e = undefined

await doc.send(
  new UpdateCommand({
    TableName: 'Users',
    Key: {pk: 'USER#1'},
    UpdateExpression: 'SET #e = :e',
    ExpressionAttributeNames: names,
    ExpressionAttributeValues: values
  })
);

DynoTable 경로

DynoTable의 업데이트 편집기는 사용자가 입력하는 대로 값을 바인딩하고 요청이 컴퓨터에서 나가기 전에 빈 자리 표시자를 거부합니다. ⌘K가 있는 항목을 열고, 필드를 편집하고, 생성된 ExpressionAttributeValues 맵을 요청 미리 보기에서 검사합니다. 불일치는 CloudWatch에서 400 대신 즉시 표시됩니다.

SDK 코드의 경우 인라인으로 실행할 수 없으면 표현식을 Expression Builder에 붙여넣고 해당 :value 맵을 자신의 맵과 비교하세요. 오류가 발생한 동일한 테이블에 대해 테스트하려면 ⌘P로 프로필을 전환하세요. 설정 → 프로필의 연결 테스트에서 자격 증명과 지역을 확인합니다. 설정: Connect to AWS, Install. 빈 세트와 정의되지 않은 JS 값이 가장 일반적인 원인입니다. 호출이 프로세스를 떠나기 전에 두 가지를 모두 보호하세요.

출처

PutItem — Amazon DynamoDB API Reference (2026-07-13 검증)
Constraints in Amazon DynamoDB (2026-07-13 인증)

참고 자료

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