ValidationException: ExpressionAttributeValues contém valor inválido

TL;DR — Um valor em ExpressionAttributeValues está vazio, tem um tipo não suportado ou um :placeholder usado em sua expressão nunca foi definido. Verifique se cada :value está presente e não vazio.

O que significa

Mensagens comuns:

ValidationException: ExpressionAttributeValues contains invalid value: One or more parameter values were invalid: An AttributeValue may not contain an empty string for key :s
ValidationException: Value provided in ExpressionAttributeValues unused in expressions: keys: {:x}
ValidationException: An expression attribute value used in expression is not defined; attribute value: :v

Por que isso acontece

String vazia / binário vazio — historicamente o DynamoDB rejeitava "". Strings vazias são permitidas hoje em atributos que não são chave (e Listas/Mapas vazios não têm problema), mas valores vazios em atributos de chave e Sets vazios continuam inválidos.
Placeholder indefinido — sua expressão referencia :v, mas ExpressionAttributeValues não tem :v.
Placeholder não usado — você definiu :x, mas nenhuma expressão o usa (o DynamoDB rejeita a requisição inteira).
Tipo errado — passar um objeto JS cru/undefined/NaN ou (com o cliente de baixo nível) o wrapper {S}/{N} errado.
Um set vazio passado para uma operação ADD/DELETE — essas cláusulas recebem operandos de set (ou, no caso do ADD, número), e um set nunca pode estar vazio.

Como corrigir

Todo :value da expressão precisa estar definido em ExpressionAttributeValues, e todo valor definido precisa ser usado — mantenha os dois em sincronia exata.
Proteja-se contra vazio/undefined. Não passe :v quando a origem for undefined; remova a cláusula em vez disso. Para sets, garanta ao menos um membro.
Use o Document Client (@aws-sdk/lib-dynamodb) para que valores JS nativos sejam marshalados para você — isso elimina a maioria dos erros de wrapper de tipo.
Audite o mapa contra a string da expressão. Imprima os dois lado a lado antes da chamada — todo :token da expressão precisa aparecer como chave em ExpressionAttributeValues, e toda chave do mapa precisa aparecer na expressão.
Em clientes de baixo nível, valide os tipos de wire. Um set vazio {SS: []} ou um wrapper de tipo ausente em um atributo de chave continua falhando mesmo com o placeholder definido.

Exemplo

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

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

const email = getEmail(); // could be undefined
const names = {'#e': 'email'};
const values = {':e': email};

if (email == null) throw new Error('email required'); // don't send :e = undefined

await doc.send(
  new UpdateCommand({
    TableName: 'Users',
    Key: {pk: 'USER#1'},
    UpdateExpression: 'SET #e = :e',
    ExpressionAttributeNames: names,
    ExpressionAttributeValues: values
  })
);

Caminho no DynoTable

O editor de atualização do DynoTable vincula os valores conforme você digita e rejeita placeholders vazios antes de a requisição sair da sua máquina. Abra o item com ⌘K, edite um campo e inspecione o mapa ExpressionAttributeValues gerado na prévia da requisição — as divergências aparecem na hora, em vez de virarem um 400 no CloudWatch.

Para código de SDK que você não consegue rodar ali mesmo, cole a expressão no Expression Builder e compare o mapa de :value dele com o seu. Troque de perfil com ⌘P para testar contra a mesma tabela que lançou o erro; o Testar conexão em Configurações → Perfis confirma credenciais e região. Configuração: Conectar ao AWS, Instalar. Sets vazios e valores JS indefinidos são as causas mais comuns — proteja-se contra os dois antes de a chamada sair do seu processo.

Fontes

PutItem — Amazon DynamoDB API Reference (verificado em 13/07/2026)
Constraints in Amazon DynamoDB (verificado em 13/07/2026)

Erros relacionados

Referências

Última verificação em 13/07/2026 em relação à documentação oficial da AWS vinculada acima.