Valor proporcionado en ExpressionAttributeNames no utilizado en expresiones

TL;DR: declaraste un marcador de posición de nombre en ExpressionAttributeNames (por ejemplo, #status) al que no hace referencia ninguna expresión. DynamoDB requiere que cada alias declarado se utilice en un KeyConditionExpression, FilterExpression, UpdateExpression, ConditionExpression, o ProjectionExpression. Elimine el alias no utilizado o corrija la expresión que se suponía que hacía referencia a él.

Qué significa

ValidationException: 1 validation error detected: Value provided in ExpressionAttributeNames unused in
expressions: keys: {#status}

# what the engine actually returns, reproduced against DynamoDB Local:
ValidationException: 1 validation error detected: Value provided in ExpressionAttributeNames unused in expressions: keys: {#status}

ExpressionAttributeNames es un mapa de sustitución para alias de nombres de atributo (necesario para palabras reservadas o nombres con caracteres especiales). DynamoDB impone un contrato estricto de doble sentido: cada alias que usas en una expresión debe declararse, y cada alias que declaras debe usarse. Una entrada sobrante, sin referenciar, dispara este HTTP 400 ValidationException. Es del lado del cliente y no reintentable hasta que el mapa coincida con las expresiones.

Por qué ocurre

Un alias obsoleto que quedó tras editar una expresión — quitaste #status = :s de la expresión pero olvidaste borrar #status del mapa de nombres.
Un mapa generado que sobre-declara — una capa de mapeo emitió alias para cada atributo, incluso los que la expresión final no toca.
El alias está en el mapa de valores, no en el de nombres — querías decir :status (un valor) pero declaraste #status (un nombre).
Un desajuste por errata — la expresión usa #stat mientras el mapa declara #status, así que #status está técnicamente sin usar.

Cómo solucionarlo

Borra de ExpressionAttributeNames el alias no usado que nombra el mensaje.
Mantén el mapa sincronizado con las expresiones — declara un #name solo cuando una expresión realmente lo referencie.
Comprueba si hay una confusión nombre-vs-valor — los alias # viven en ExpressionAttributeNames, los marcadores de posición : en ExpressionAttributeValues.
Regenera la solicitud para que nombres, valores y texto de expresión se construyan juntos en lugar de ensamblarse a mano.

Inspecciónalo en DynoTable

DynoTable pone alias a los nombres de atributo reservados en los editores de actualización y de filtros — cada #placeholder de la salida está referenciado en la expresión. Abre una tabla con ⌘K, edita un Item y copia el mapa ExpressionAttributeNames generado.

Contrasta las peticiones fallidas del SDK en el comprobador de palabras reservadas — imprime el mapa de alias para los nombres que necesitan prefijo #. 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)

Reproducirlo

Una entrada de ExpressionAttributeNames que ninguna expresión referencia:

await client.send(
  new UpdateItemCommand({
    TableName: 'orders',
    Key: {pk: {S: 'ORDER#1'}, sk: {S: 'META'}},
    UpdateExpression: 'SET stat = :v', // note: 'stat', not '#unused'
    ExpressionAttributeNames: {'#unused': 'status'},
    ExpressionAttributeValues: {':v': {S: 'shipped'}}
  })
);

Salida real:

ValidationException: 1 validation error detected: Value provided in ExpressionAttributeNames unused in expressions: keys: {#unused}
HTTP 400

El mensaje nombra la clave culpable, lo que lo convierte en uno de los pocos errores de validación de DynamoDB sobre los que puedes actuar sin leer nada más. Suele aparecer después de que una edición quite un marcador de posición de la expresión pero deje atrás su declaración.

Errores relacionados

Valor proporcionado en ExpressionAttributeValues no utilizado en expresiones — la misma regla para los marcadores de posición :value.
La expresión proporcionada hace referencia a un atributo que no existe en el Item — la expresión lee un atributo del Item que no está ahí.
El nombre del atributo es una palabra clave reservada — por qué necesitabas un alias # en primer lugar.
Aprende: Expression names & values

Referencias

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

Reproducido el 2026-07-26 contra DynamoDB Local 2.x con AWS SDK for JavaScript v3.1095.0 — la salida de arriba es literal.