ValidationException: ExpressionAttributeValues contiene un valor no válido

TL;DR: un valor en ExpressionAttributeValues está vacío, tiene un tipo no admitido o un :placeholder usado en su expresión nunca se definió. Verifique que cada :value esté presente y no esté vacío.

Qué significa

Mensajes comunes:

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 qué ocurre

Cadena vacía / binario vacío — históricamente DynamoDB rechazaba "". Las cadenas vacías sí se permiten ahora en atributos que no son clave (y las Listas/Mapas vacíos están bien), pero los valores vacíos en atributos de clave y los Sets vacíos siguen siendo inválidos.
Placeholder no definido — tu expresión hace referencia a :v pero ExpressionAttributeValues no tiene :v.
Placeholder sin usar — definiste :x pero ninguna expresión lo usa (DynamoDB rechaza toda la solicitud).
Tipo equivocado — pasar un objeto JS en crudo/undefined/NaN, o (con el cliente de bajo nivel) el wrapper {S}/{N} equivocado.
Un set vacío pasado a una operación ADD/DELETE — esas cláusulas toman operandos de tipo set (o, para ADD, número), y un set nunca puede estar vacío.

Cómo solucionarlo

Cada :value de la expresión debe estar definido en ExpressionAttributeValues, y cada valor definido debe usarse — mantén ambos en sincronía exacta.
Protégete frente a valores vacíos/undefined. No pases :v cuando el origen sea undefined; elimina la cláusula en su lugar. Para los sets, asegúrate de que haya al menos un miembro.
Usa el Document Client (@aws-sdk/lib-dynamodb) para que los valores JS nativos se marshalen por ti — elimina la mayoría de los errores con los wrappers de tipo.
Audita el mapa contra la cadena de la expresión. Imprime ambos lado a lado antes de la llamada — cada :token de la expresión debe aparecer como clave en ExpressionAttributeValues, y cada clave del mapa debe aparecer en la expresión.
Con clientes de bajo nivel, valida los tipos de red. Un set vacío {SS: []} o un wrapper de tipo ausente en un atributo de clave siguen fallando aunque el placeholder esté definido.

Ejemplo

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

Ruta en DynoTable

El editor de actualizaciones de DynoTable vincula los valores a medida que escribe y rechaza los marcadores de posición vacíos antes de que la solicitud abandone su máquina. Abra el elemento con ⌘K, edite un campo e inspeccione el mapa ExpressionAttributeValues generado en la vista previa de la solicitud; las discrepancias aparecen inmediatamente en lugar de como 400 en CloudWatch.

Para el código SDK que no puede ejecutar en línea, pegue la expresión en el Generador de expresiones y compare su mapa :value con el suyo. Cambie de perfil con ⌘P para probar con la misma tabla que arrojó el error; Probar conexión en Configuración → Perfiles confirma las credenciales y la región. Configuración: Conectar a AWS, Instalar. Los conjuntos vacíos y los valores JS no definidos son las causas más comunes: proteja ambos antes de que la llamada abandone su proceso.

Fuentes

PutItem — Amazon DynamoDB API Reference (verificado el 2026-07-13)
Constraints in Amazon DynamoDB (verificado el 2026-07-13)

Errores relacionados

Referencias

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