An operand in the update expression has an incorrect data type

TL;DR — A ação da atualização é verificada de tipo contra o que está de fato armazenado (e contra o valor que você enviou), e um deles não encaixa: ADD contra um atributo que não é número nem set, list_append contra algo que não é uma list, ou um operando de set cujo tipo de elemento não corresponde ao set armazenado. Combine o operando com o tipo armazenado — ou corrija o item cujo tipo desviou.

O que significa

ValidationException: An operand in the update expression has an incorrect data type

Ações de atualização têm regras de tipo estritas: ADD funciona apenas em números e sets (SS/NS/BS), DELETE apenas em sets, e list_append recebe duas lists. O DynamoDB avalia a expressão contra os tipos de atributo atuais do item no momento da escrita — então a mesma requisição pode ser bem-sucedida em um item e falhar em outro cujo atributo contém um tipo diferente. Um primo próximo é rejeitado antes, no momento do parse da expressão, quando o tipo do valor enviado nunca pode encaixar no operador:

ValidationException: Invalid UpdateExpression: Incorrect operand type for
operator or function; operator: ADD, operand type: LIST

Por que acontece

• ADD counter :one mas counter está armazenado como uma string — por exemplo, o item foi importado com "5" (tipo S) em vez de 5 (tipo N).
• ADD tags :t com um operando de list (L) — ADD coleta em sets, não lists. Lists são anexadas com SET + list_append.
• list_append(mylist, :v) onde mylist é um map, set ou escalar — ambos os argumentos precisam ser lists (envolva um único elemento como uma list de um item).
• Incompatibilidade de tipo de elemento de set — ADD/DELETE com um operando de set de string (SS) contra um set de número armazenado (NS), ou vice-versa.
• Desvio de tipo entre itens — processos de escrita mistos (uma importação antiga, outro serviço) deixaram o mesmo atributo como N em alguns itens e S em outros, então a atualização falha apenas às vezes.

Como corrigir

1. Contadores: armazene o valor como um número e envie um operando de número:

   UpdateExpression: 'ADD #c :one',
   ExpressionAttributeValues: {':one': 1}   // {N: "1"} — not a string

2. Lists: use SET com list_append, e envolva o novo elemento em uma list:

   UpdateExpression: 'SET #l = list_append(if_not_exists(#l, :empty), :new)',
   ExpressionAttributeValues: {':new': ['item'], ':empty': []}

3. Sets: mantenha os operandos de ADD/DELETE no mesmo tipo de set que o atributo armazenado (SS com SS, NS com NS).

4. Corrija itens desviados — encontre os itens cujo atributo carrega o tipo errado e reescreva-os uma vez; o sintoma "a mesma atualização falha em alguns itens" é sempre dados, não código.

Desvio de tipo é invisível na maioria dos consoles — o app desktop DynoTable exibe o tipo armazenado real de cada atributo ao lado de seu valor, então um contador "5"-como-string se destaca imediatamente.

Erros relacionados

• Float types are not supported — atrito de tipo de número pelo lado do SDK.
• Number overflow
• Type mismatch: key element does not match schema
• Aprenda: Update expressions · Atomic counters · Data types

Referências

• Using update expressions in DynamoDB — Amazon DynamoDB Developer Guide
• TransactWriteItems — Amazon DynamoDB API Reference
• Supported data types and naming rules in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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