ExpressionAttributeNames contiene una clave no válida: error de sintaxis

TL;DR: el problema es la clave de marcador de posición en el lado izquierdo de su mapa ExpressionAttributeNames, no el atributo al que apunta. Un marcador de posición debe ser # seguido de letras simples, dígitos o guiones bajos (#name, #p0). Si coloca el nombre real del atributo (con sus puntos, guiones, + signos o espacios) en el marcador de posición, DynamoDB rechaza el mapa. Mantenga los marcadores de posición aburridos; pon el nombre real desordenado en el lado derecho.

Qué significa

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 mapea un token de marcador de posición (usado dentro de tu expresión) a un nombre de atributo real. DynamoDB valida la sintaxis del marcador de posición antes de tocar tus datos: debe empezar por # y contener solo caracteres válidos dentro de un token de expresión. Los caracteres especiales que significan algo en la gramática de la expresión — . (separador de ruta), -, +, espacios — hacen que el propio marcador de posición no sea analizable, y toda la solicitud se rechaza con esta ValidationException.

Por qué ocurre

El nombre real del atributo se copió en el marcador de posición — p. ej. {"#stats.daily": "stats.daily"}. El punto en la clave es un error de sintaxis, independientemente de lo que mapee.
Caracteres especiales en el marcador de posición — guiones (#user-id), signos + o espacios. Solo los alfanuméricos y los guiones bajos son seguros después del #.
Un # ausente — las claves de ExpressionAttributeNames deben empezar por #; {"name": "name"} es inválido.
Una librería que autogenera marcadores de posición a partir de nombres de atributo que contienen puntos o caracteres especiales, pasando el carácter directamente.

Cómo solucionarlo

Usa marcadores de posición simples y mapea cada uno al nombre real:

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

Para rutas anidadas, alias cada segmento por separado — un marcador de posición por elemento de ruta, unidos por un punto literal en la expresión:
```
// read stats.daily where the item has a top-level "stats" map
{
  ProjectionExpression: '#s.#d',
  ExpressionAttributeNames: {'#s': 'stats', '#d': 'daily'}
}
```
Fíjate en el reverso: si el nombre real del atributo contiene un punto literal (un atributo llamado "stats.daily", no una ruta anidada), un único marcador de posición para el nombre completo es exactamente lo que quieres — {'#sd': 'stats.daily'} — para que el punto se trate como parte del nombre, no como un separador de ruta.
Comprueba qué genera tu wrapper — si un ODM/helper construye el mapa por ti, registra la solicitud final e inspecciona las claves de marcador de posición que produjo.
Nunca pongas separadores de ruta en las claves de marcador de posición. Los puntos van en la cadena de la expresión, entre tokens #segment, no dentro de una única clave #.

Compruébalo en DynoTable

DynoTable construye las consultas con marcadores de posición simples con prefijo # — los nombres de atributo con puntos, guiones o palabras reservadas quedan correctamente aliasados en el lado derecho del mapa. Abre una tabla con ⌘K, añade filtros y copia el ExpressionAttributeNames generado.

Contrasta los nombres de atributo en el comprobador de palabras reservadas cuando escribas los alias a mano. Cambia de perfil con ⌘P; consulta Conectar con AWS e Instalación.

Fuentes

Expression attribute names (aliases) in DynamoDB (verificado el 2026-07-13)
Reserved words in DynamoDB (verificado el 2026-07-13)

Errores relacionados

Attribute name is a reserved keyword — la otra gran razón para usar ExpressionAttributeNames.
Valor proporcionado en ExpressionAttributeNames no utilizado en expresiones
Valor proporcionado en ExpressionAttributeValues no utilizado
Aprende: Expression names & values

Referencias

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.