ValidationException: el error "Query condition missed key schema element"

TL;DR — Tu KeyConditionExpression debe incluir una igualdad (=) sobre la partition key. Si consultas por un atributo que no es clave, necesitas una Query sobre un GSI/LSI que tenga ese atributo como clave — o un Scan con una FilterExpression.

Qué significa

El mensaje completo suele ser:

ValidationException: Query condition missed key schema element: pk

El nombre que sigue a los dos puntos es el atributo de partition key de tu tabla, así que varía.

Query solo funciona contra una clave. DynamoDB te está diciendo que la KeyConditionExpression o bien omite la partition key por completo, o bien nombra un atributo que no es la partition key ni la sort key de la tabla (o del índice que estás consultando).

Por qué ocurre

• La KeyConditionExpression filtra por un atributo normal (p. ej. email, status) en lugar de la partition key.
• Estás consultando la tabla base pero el atributo solo es clave en un GSI — olvidaste IndexName.
• La partition key está presente pero con un operador distinto de = (la partition key debe ser una coincidencia exacta; solo la sort key admite <, >, begins_with, between).
• Una errata en el nombre del atributo, de modo que ya no coincide con el esquema.

Cómo solucionarlo

1. Consulta por la partition key con =. Toda Query necesita pk = :pk (usando el nombre real de la clave de tu tabla).
2. ¿Necesitas consultar por un atributo que no es clave? Crea un GSI con ese atributo como partition key y pasa IndexName.
3. ¿Solo necesitas acceso ocasional? Usa Scan con una FilterExpression en lugar de Query — pero ten en cuenta que Scan lee toda la tabla.

Ejemplo

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

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

// Query the base table by its partition key:
await doc.send(
  new QueryCommand({
    TableName: 'Orders',
    KeyConditionExpression: 'pk = :pk',
    ExpressionAttributeValues: {':pk': 'USER#123'}
  })
);

// Query by a non-key attribute → use a GSI that keys on it
// ("status" is a DynamoDB reserved word, so alias it with #status):
await doc.send(
  new QueryCommand({
    TableName: 'Orders',
    IndexName: 'byStatus',
    KeyConditionExpression: '#status = :s',
    ExpressionAttributeNames: {'#status': 'status'},
    ExpressionAttributeValues: {':s': 'SHIPPED'}
  })
);

FAQ

¿Qué significa "Query condition missed key schema element"? Tu KeyConditionExpression o bien omite la partition key por completo o bien nombra un atributo que no es la partition key ni la sort key de la tabla o índice que estás consultando. Toda Query necesita una condición de igualdad sobre la partition key.

¿Cómo consulto DynamoDB por un atributo que no es clave? Crea un GSI con ese atributo como partition key y pasa IndexName en la Query — o, para acceso ocasional, usa un Scan con una FilterExpression, teniendo en cuenta que un Scan lee toda la tabla.

Reproducirlo

Una Query cuya condición solo nombra la clave de ordenación:

await client.send(
  new QueryCommand({
    TableName: 'orders',
    KeyConditionExpression: 'sk = :s',
    ExpressionAttributeValues: {':s': {S: 'META'}}
  })
);

Salida real:

ValidationException: Query condition missed key schema element
HTTP 400

Toda Query debe fijar exactamente una clave de partición. Querer buscar solo por la clave de ordenación es la señal clásica de que el patrón de acceso necesita un GSI en lugar de una Query — o, si de verdad tienes que leer todas las particiones, un Scan.

Errores relacionados

• El elemento de clave proporcionado no coincide con el esquema
• ValidationException (visión general)
• Ejemplo de código: Query en Node.js · en Python (boto3) — una KeyConditionExpression bien hecha.
• Aprende: Query vs Scan · Expresiones de condición de clave

Referencias

• Query — Amazon DynamoDB API Reference
• Reserved words in DynamoDB — Amazon DynamoDB Developer Guide
• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide

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

Reproducido el 2026-07-26 contra DynamoDB Local 2.x con AWS SDK for JavaScript v3.1095.0 — la salida de arriba es literal.