ExpressionAttributeNames에 잘못된 키가 포함되어 있습니다: 구문 오류

TL;DR — 문제는 ExpressionAttributeNames 지도 왼쪽에 있는 자리 표시자 키이지 그것이 가리키는 속성이 아닙니다. 자리 표시자는 # 뒤에 일반 문자, 숫자 또는 밑줄(#name, #p0)이 와야 합니다. 점, 하이픈, + 기호 또는 공백이 포함된 실제 속성 이름을 자리 표시자 자체에 입력하면 DynamoDB는 맵을 거부합니다. 자리 표시자를 지루하게 유지하세요. 지저분한 실명을 오른쪽에 넣으세요.

무엇을 의미하는가

ValidationException: 1 validation error detected: ExpressionAttributeNames contains invalid key:
Syntax error; key: "#my.attribute"

# what the engine actually returns, reproduced against DynamoDB Local:
ValidationException: 1 validation error detected: ExpressionAttributeNames contains invalid key: Syntax error; key: "#my.attribute"

ExpressionAttributeNames는 자리 표시자 토큰(표현식 내에서 사용됨)을 실제 속성 이름에 매핑합니다. DynamoDB는 데이터를 다루기 전에 자리 표시자의 구문을 검증합니다. 자리 표시자는 #로 시작해야 하며 표현식 토큰 내에서 유효한 문자만 포함해야 합니다. 표현식 문법에서 무언가를 의미하는 특수 문자(.(경로 구분 기호), -, +, 공백)는 자리 표시자 자체를 구문 분석할 수 없게 만들고 이 ValidationException`를 사용하면 전체 요청이 거부됩니다.

왜 발생하는가

실제 속성 이름이 자리 표시자에 복사되었습니다 — 예: {"#stats.daily": "stats.daily"}. _key_의 점은 매핑 대상에 관계없이 구문 오류입니다.
자리 표시자의 특수 문자 — 하이픈(#user-id), + 기호 또는 공백. # 다음에는 영숫자와 밑줄만 사용할 수 있습니다.
누락된 # — ExpressionAttributeNames의 키는 #로 시작해야 합니다. {"name": "name"}은 유효하지 않습니다.
점이나 특수 문자가 포함된 속성 이름에서 자리 표시자를 자동 생성하는 라이브러리로 문자를 바로 전달합니다.

어떻게 해결하는가

간단한 자리 표시자를 사용하고 각각을 실제 이름에 매핑합니다.

{
  ExpressionAttributeNames: {'#p0': 'user-id', '#p1': 'stats'},
  KeyConditionExpression: '#p0 = :uid'
}

중첩 경로의 경우 각 세그먼트에 별도로 별칭을 지정합니다 — 경로 요소당 자리 표시자 하나를 지정하고 표현식에서 리터럴 점으로 연결합니다.
```
// read stats.daily where the item has a top-level "stats" map
{
  ProjectionExpression: '#s.#d',
  ExpressionAttributeNames: {'#s': 'stats', '#d': 'daily'}
}
```
참고: 속성의 _실제 이름_에 리터럴 점이 포함되어 있는 경우(중첩 경로가 아닌 "stats.daily"라는 속성 하나) 전체 이름에 대한 단일 자리 표시자가 정확히 원하는 것({'#sd': 'stats.daily'})이므로 점이 경로 구분 기호가 아닌 이름의 일부로 처리됩니다.
래퍼가 생성하는 내용을 확인하세요 — ODM/도우미가 맵을 빌드하는 경우 최종 요청을 기록하고 생성된 자리 표시자 키를 검사하세요.
자리 표시자 키에 경로 구분 기호를 넣지 마십시오. 점은 단일 # 키 내부가 아니라 #segment 토큰 사이의 표현식 문자열에 속합니다.

DynoTable에서 확인

DynoTable은 # 접두사가 붙은 간단한 자리 표시자를 사용하여 쿼리를 작성합니다. 점, 대시 또는 예약어가 포함된 속성 이름은 지도 오른쪽에 올바르게 별칭이 지정됩니다. ⌘K가 있는 테이블을 열고 필터를 추가한 후 생성된 ExpressionAttributeNames을 복사합니다.

별칭을 직접 작성할 때 reserved words checker에서 속성 이름을 교차 확인하세요. ⌘P로 프로필을 전환합니다. Connect to AWS 및 Install를 참조하세요.

출처

Expression attribute names (aliases) in DynamoDB (2026-07-13 인증)
Reserved words in DynamoDB (2026-07-13 인증)

참고 자료

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