ValidationException: UpdateExpression no válido

TL;DR: Tu UpdateExpression tiene un formato incorrecto. Nueve de cada diez veces es una palabra clave reservada (como status, name, size) que se usa directamente; cámbiala por #placeholder en ExpressionAttributeNames. El mensaje nombra exactamente token.

Qué significa

Mensajes típicos:

ValidationException: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: status
ValidationException: Invalid UpdateExpression: Syntax error; token: "=", near: "SET status ="
ValidationException: Invalid UpdateExpression: An expression attribute value used in expression is not defined; attribute value: :s

DynamoDB analiza la cadena de la expresión y rechaza cualquier cosa que no sea gramática válida o que haga referencia a un placeholder no definido.

Por qué ocurre

• Palabra reservada usada en crudo. DynamoDB tiene cientos de palabras reservadas — status, name, size, count, data, year. Usadas directamente en una expresión provocan un error de sintaxis. El comprobador de palabras reservadas contrasta tus nombres de atributo con la lista completa y emite el mapa de alias.
• Falta una entrada en ExpressionAttributeNames para un #name al que hiciste referencia.
• Falta una entrada en ExpressionAttributeValues para un :value al que hiciste referencia.
• Gramática de verbo incorrecta — mezclar cláusulas de forma incorrecta (SET, REMOVE, ADD, DELETE cada una tiene su propia sintaxis), o un = suelto.
• Nombre de atributo con caracteres especiales (puntos, guiones) usado sin un placeholder.

Cómo solucionarlo

1. Alias a cada nombre de atributo mediante ExpressionAttributeNames (#status) — esquiva por completo la lista de palabras reservadas, así que poner alias a todo es un hábito seguro.
2. Define cada :value al que hagas referencia en ExpressionAttributeValues.
3. Usa la cláusula correcta. SET para escribir/sobrescribir, REMOVE para eliminar un atributo, ADD para incrementos atómicos de número/conjunto, DELETE para eliminar de un conjunto.
4. Pasa la comprobación de palabras reservadas antes de desplegar. Pega tus nombres de atributo en el comprobador de palabras reservadas — marca cada nombre que esté en la lista de AWS e imprime el mapa de #alias que necesitas.
5. Construye la expresión una vez y cópiala a todas partes. Una cadena editada a mano deriva; genera el UpdateExpression completo y ambos mapas de atributos desde una sola fuente para que los placeholders sigan emparejados.

Ejemplo

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, UpdateCommand} from '@aws-sdk/lib-dynamodb';

const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));

await doc.send(
  new UpdateCommand({
    TableName: 'Orders',
    Key: {pk: 'ORDER#1'},
    // #status aliases the reserved word "status"
    UpdateExpression: 'SET #status = :s, updatedAt = :t',
    ExpressionAttributeNames: {'#status': 'status'},
    ExpressionAttributeValues: {':s': 'SHIPPED', ':t': Date.now()}
  })
);

Revisa primero en DynoTable

Cuando falla una actualización en tu aplicación, reprodúcela en DynoTable antes de cambiar el código de producción. Abre la tabla con ⌘K, selecciona el Item y usa el editor de actualización en línea: DynoTable pone alias a los nombres de atributo reservados automáticamente y muestra el UpdateExpression generado con ambos mapas de atributos. El staging (⌘S) te permite previsualizar la edición y detectar errores de sintaxis antes de confirmarla.

Para correcciones por lotes, pega la expresión fallida en el Expression Builder y compara su salida con lo que envía tu SDK. El cambio de perfil (⌘P) mantiene las pruebas en la misma cuenta que vio el error; usa Test Connection en Ajustes → Perfiles para confirmar que el perfil coincide. Consulta Conectar a AWS e Instalar para configurar el perfil. Contrasta los nombres de atributo con el comprobador de palabras reservadas cuando el error nombre un token concreto como status o data. Poner alias a cada nombre de atributo — no solo a los reservados — es un hábito seguro que evita por completo esta clase de error.

Fuentes

• Using update expressions in DynamoDB (verificado 2026-07-13)
• Reserved words in DynamoDB (verificado 2026-07-13)

Errores relacionados

• ExpressionAttributeValues contiene un valor no válido
• ValidationException (resumen)
• Ejemplo de código: UpdateItem en Node.js · en Python (boto3) — un UpdateExpression válido con #names y :values.
• Aprende: Update expressions · Nombres y valores de expresión

Referencias

• Using update expressions in DynamoDB — Amazon DynamoDB Developer Guide
• Reserved words in DynamoDB — Amazon DynamoDB Developer Guide
• Expression attribute names (aliases) in DynamoDB — Amazon DynamoDB Developer Guide

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