ExpressionAttributeNames contains invalid key: Syntax error

In breve — Il problema è la chiave placeholder sul lato sinistro della tua mappa ExpressionAttributeNames, non l'attributo a cui punta. Un placeholder deve essere # seguito da semplici lettere, cifre o underscore (#name, #p0). Se metti il nome reale dell'attributo — con i suoi punti, trattini, segni + o spazi — nel placeholder stesso, DynamoDB rifiuta la mappa. Mantieni i placeholder banali; metti il nome reale disordinato sul lato destro.

Cosa significa

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

ExpressionAttributeNames mappa un token placeholder (usato all'interno della tua espressione) a un nome reale di attributo. DynamoDB valida la sintassi del placeholder prima di toccare i tuoi dati: deve iniziare con # e contenere solo caratteri validi all'interno di un token di espressione. I caratteri speciali che hanno un significato nella grammatica delle espressioni — . (separatore di percorso), -, +, spazi — rendono il placeholder stesso non analizzabile, e l'intera richiesta viene rifiutata con questa ValidationException.

Perché accade

Il nome reale dell'attributo è stato copiato nel placeholder — es. {"#stats.daily": "stats.daily"}. Il punto nella chiave è un errore di sintassi, indipendentemente da ciò a cui mappa.
Caratteri speciali nel placeholder — trattini (#user-id), segni +, o spazi. Solo alfanumerici e underscore sono sicuri dopo il #.
Un # mancante — le chiavi in ExpressionAttributeNames devono iniziare con #; {"name": "name"} non è valido.
Una libreria che auto-genera placeholder dai nomi degli attributi che contengono punti o caratteri speciali, passando il carattere direttamente.

Come correggerlo

Usa placeholder semplici e mappa ciascuno al nome reale:

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

Per i percorsi nidificati, usa un alias separato per ogni segmento — un placeholder per elemento del percorso, uniti da un punto letterale nell'espressione:
```
// read stats.daily where the item has a top-level "stats" map
{
  ProjectionExpression: '#s.#d',
  ExpressionAttributeNames: {'#s': 'stats', '#d': 'daily'}
}
```
Nota il rovescio della medaglia: se il nome effettivo dell'attributo contiene un punto letterale (un attributo chiamato "stats.daily", non un percorso nidificato), un singolo placeholder per l'intero nome è esattamente ciò che vuoi — {'#sd': 'stats.daily'} — così il punto è trattato come parte del nome, non come separatore di percorso.
Controlla cosa genera il tuo wrapper — se un ODM/helper costruisce la mappa per te, logga la richiesta finale e ispeziona le chiavi placeholder che ha prodotto.

Stai lavorando con attributi i cui nomi sono pieni di punti e trattini? L'app desktop DynoTable costruisce automaticamente le sue query con nomi correttamente aliasati, comunque si chiami l'attributo.

Errori correlati

Attribute name is a reserved keyword — l'altra grande ragione per usare ExpressionAttributeNames.
Value provided in ExpressionAttributeNames unused in expressions
Value provided in ExpressionAttributeValues unused
Impara: Expression names & values

References

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.