ValidationException: UpdateExpression inválida

TL;DR — Seu UpdateExpression está malformado. Nove em cada dez vezes é uma palavra-chave reservada (como status, name, size) usada diretamente – troque-a por #placeholder em ExpressionAttributeNames. A mensagem nomeia o token exato.

O que significa

Mensagens típicas:

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

O DynamoDB analisa a string da expressão e rejeita qualquer coisa que não seja gramática válida ou que referencie um placeholder indefinido.

Por que isso acontece

Palavra reservada usada crua. O DynamoDB tem centenas de palavras reservadas — status, name, size, count, data, year. Usadas diretamente em uma expressão, elas causam um erro de sintaxe. O verificador de palavras reservadas testa seus nomes de atributo contra a lista completa e emite o mapa de aliases.
Falta a entrada em ExpressionAttributeNames para um #name que você referenciou.
Falta a entrada em ExpressionAttributeValues para um :value que você referenciou.
Gramática de verbo errada — misturar cláusulas incorretamente (SET, REMOVE, ADD, DELETE têm cada uma a sua sintaxe) ou um = perdido.
Nome de atributo com caracteres especiais (pontos, hífens) usado sem um placeholder.

Como corrigir

Apelide todo nome de atributo por meio de ExpressionAttributeNames (#status) — isso contorna a lista de palavras reservadas por completo, então apelidar tudo é um hábito seguro.
Defina todo :value que você referenciar em ExpressionAttributeValues.
Use a cláusula certa. SET para gravar/sobrescrever, REMOVE para excluir um atributo, ADD para incrementos atômicos de número/set, DELETE para remover de um set.
Rode a checagem de palavras reservadas antes de publicar. Cole seus nomes de atributo no verificador de palavras reservadas — ele sinaliza todo nome da lista da AWS e imprime o mapa de #alias de que você precisa.
Monte a expressão uma vez e copie para todo lugar. Uma string editada à mão desvia; gere o UpdateExpression completo mais os dois mapas de atributos a partir de uma única fonte, para que os placeholders continuem pareados.

Exemplo

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()}
  })
);

Confira primeiro no DynoTable

Quando uma atualização falha no seu app, reproduza-a no DynoTable antes de mexer no código de produção. Abra a tabela com ⌘K, selecione o item e use o editor de update inline — o DynoTable apelida nomes de atributo reservados automaticamente e mostra o UpdateExpression gerado com os dois mapas de atributos. O staging (⌘S) permite pré-visualizar a edição e pegar erros de sintaxe antes do commit.

Para correções em lote, cole a expressão que está falhando no Expression Builder e compare a saída dele com o que seu SDK envia. A troca de perfil (⌘P) mantém os testes na mesma conta em que o erro apareceu; use Test Connection em Settings → Profiles para confirmar que o perfil bate. Veja Connect to AWS e Install para configurar perfis. Confira os nomes de atributo no verificador de palavras reservadas quando o erro nomear um token específico como status ou data. Apelidar todo nome de atributo — não apenas os reservados — é um hábito seguro que elimina essa classe de erro por completo.

Fontes

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

Erros relacionados

ExpressionAttributeValues contém um valor inválido
ValidationException (visão geral)
Exemplo de código: UpdateItem in Node.js · in Python (boto3) — um UpdateExpression válido com #names e :values.
Aprenda: Update expressions · Expression names & values

Referências

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.