ExpressionAttributeNames contains invalid key: Syntax error

요약 — 문제는 ExpressionAttributeNames map의 왼쪽에 있는 플레이스홀더 키 이지, 그것이 가리키는 속성이 아닙니다. 플레이스홀더는 # 뒤에 일반 문자, 숫자, 또는 밑줄이 와야 합니다(#name, #p0). 실제 속성 이름을 — 점, 하이픈, + 기호, 공백과 함께 — 플레이스홀더 자체에 넣으면 DynamoDB가 map을 거부합니다. 플레이스홀더는 단순하게 유지하고, 지저분한 실제 이름은 오른쪽에 두세요.

무엇을 의미하나요

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

ExpressionAttributeNames는 플레이스홀더 토큰(표현식 안에서 사용)을 실제 속성 이름에 매핑합니다. DynamoDB는 데이터를 건드리기 전에 플레이스홀더의 구문을 검증합니다: #으로 시작하고 표현식 토큰 내에서 유효한 문자만 포함해야 합니다. 표현식 문법에서 의미를 갖는 특수 문자 — .(경로 구분자), -, +, 공백 — 는 플레이스홀더 자체를 파싱할 수 없게 만들고, 전체 요청이 이 ValidationException으로 거부됩니다.

왜 발생하나요

실제 속성 이름이 플레이스홀더에 복사됨 — 예: {"#stats.daily": "stats.daily"}. 키 의 점은 무엇에 매핑되든 구문 오류입니다.
플레이스홀더의 특수 문자 — 하이픈(#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/헬퍼가 map을 대신 만든다면, 최종 요청을 로깅하고 생성한 플레이스홀더 키를 검사하세요.

이름이 점과 대시로 가득한 속성을 다루나요? DynoTable 데스크톱 앱은 속성 이름이 무엇이든 올바르게 별칭된 이름으로 쿼리를 자동으로 만듭니다.

References

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

ExpressionAttributeNames contains invalid key: Syntax error

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

관련 오류

References