ExpressionAttributeNames contains invalid key: Syntax error

TL;DR — Le problème vient de la clé de placeholder située à gauche de ta map ExpressionAttributeNames, pas de l'attribut vers lequel elle pointe. Un placeholder doit être un # suivi de simples lettres, chiffres ou underscores (#name, #p0). Si tu mets le vrai nom d'attribut — avec ses points, tirets, signes + ou espaces — dans le placeholder lui-même, DynamoDB rejette la map. Garde des placeholders banals ; mets le vrai nom compliqué du côté droit.

Ce que ça signifie

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 associe un jeton de placeholder (utilisé dans ton expression) à un vrai nom d'attribut. DynamoDB valide la syntaxe du placeholder avant de toucher à tes données : il doit commencer par # et ne contenir que des caractères valides dans un jeton d'expression. Les caractères spéciaux qui ont un sens dans la grammaire d'expression — . (séparateur de chemin), -, +, espaces — rendent le placeholder lui-même impossible à analyser, et toute la requête est rejetée avec cette ValidationException.

Pourquoi ça arrive

Le vrai nom d'attribut a été copié dans le placeholder — par ex. {"#stats.daily": "stats.daily"}. Le point dans la clé est une erreur de syntaxe, quel que soit ce vers quoi il pointe.
Des caractères spéciaux dans le placeholder — tirets (#user-id), signes + ou espaces. Seuls les caractères alphanumériques et les underscores sont sûrs après le #.
Un # manquant — les clés de ExpressionAttributeNames doivent commencer par # ; {"name": "name"} est invalide.
Une bibliothèque qui auto-génère des placeholders à partir de noms d'attributs contenant des points ou des caractères spéciaux, laissant passer le caractère tel quel.

Comment le corriger

Utilise des placeholders simples et associe chacun au vrai nom :

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

Pour les chemins imbriqués, aliase chaque segment séparément — un placeholder par élément de chemin, joints par un point littéral dans l'expression :
```
// read stats.daily where the item has a top-level "stats" map
{
  ProjectionExpression: '#s.#d',
  ExpressionAttributeNames: {'#s': 'stats', '#d': 'daily'}
}
```
Note le revers : si le nom réel de l'attribut contient un point littéral (un seul attribut nommé "stats.daily", pas un chemin imbriqué), un seul placeholder pour le nom entier est exactement ce qu'il te faut — {'#sd': 'stats.daily'} — pour que le point soit traité comme faisant partie du nom, et non comme un séparateur de chemin.
Vérifie ce que génère ton wrapper — si un ODM/helper construit la map à ta place, journalise la requête finale et inspecte les clés de placeholder qu'il a produites.

Tu travailles avec des attributs dont les noms sont pleins de points et de tirets ? L'application de bureau DynoTable construit ses requêtes avec des noms correctement aliasés automatiquement, quel que soit le nom de l'attribut.

Vérifie dans DynoTable

DynoTable construit ses requêtes avec de simples placeholders préfixés par # — les noms d'attributs à points, à tirets ou qui sont des mots réservés sont aliasés correctement du bon côté de la map. Ouvre une table avec ⌘K, ajoute des filtres, et copie les ExpressionAttributeNames générés.

Recoupe les noms d'attributs dans le vérificateur de mots réservés quand tu écris les alias à la main. Change de profil avec ⌘P ; vois Se connecter à AWS et Installation.

Sources

Expression attribute names (aliases) in DynamoDB (vérifié le 2026-07-13)
Reserved words in DynamoDB (vérifié le 2026-07-13)

Erreurs liées

Attribute name is a reserved keyword — l'autre grande raison d'utiliser ExpressionAttributeNames.
Value provided in ExpressionAttributeNames unused in expressions
Value provided in ExpressionAttributeValues unused
Apprends : Expression names & values

Références

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.