La expresión de filtro solo puede contener atributos de clave no principal

TL;DR: colocas un atributo de clave principal (clave de partición o clave de clasificación, de la tabla o el índice que estás consultando) dentro de un FilterExpression. DynamoDB prohíbe eso: los atributos de clave van en KeyConditionExpression, y un filtro solo puede hacer referencia a atributos que no son clave. Mueva la condición clave a donde pertenece.

Qué significa

ValidationException: Filter Expression can only contain non-primary key attributes:
Primary key attribute: <name>

# what the engine actually returns, reproduced against DynamoDB Local:
ValidationException: Filter Expression can only contain non-primary key attributes: Primary key attribute: pk

FilterExpression se ejecuta después de que se leen los Items, para descartar filas que no quieres; KeyConditionExpression se ejecuta antes, para seleccionar qué Items se leen por clave. Referenciar una clave de partición/ordenación en el filtro mezcla esos roles, así que DynamoDB lo rechaza con un ValidationException HTTP 400 — del lado del cliente y no reintentable hasta que reestructures.

Por qué ocurre

Una condición de clave escrita como filtro — FilterExpression: 'sk = :v' donde sk es la clave de ordenación; pertenece a KeyConditionExpression.
Filtrar por la clave del índice — cuando haces Query sobre un GSI/LSI, la clave de partición/ordenación de ese índice son "atributos de clave primaria" para esta consulta y no pueden aparecer en el filtro.
Copiar y pegar un filtro de scan en una query donde uno de los atributos filtrados resulta ser una clave.
Intentar añadir una segunda condición sobre la clave de ordenación mediante el filtro (p. ej. un rango) en lugar de expresarla en la condición de clave.

Cómo solucionarlo

Mueve las condiciones de clave a KeyConditionExpression:

KeyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',
// FilterExpression: only NON-key attributes, e.g. 'status = :active'

Usa el índice correcto. Si necesitas filtrar/seleccionar por un atributo que no es clave, modélalo como la clave de partición/ordenación de un GSI y consulta ese índice por clave.
Reserva el filtro solo para atributos que no son clave — recorta resultados pero aun así consume capacidad de lectura por cada Item escaneado, así que apóyate en claves/índices para la selección.
¿Consultas un GSI? Recuerda que sus atributos de clave también quedan vetados en el filtro — condiciónalos en la condición de clave.
Audita las peticiones generadas. Registra juntos KeyConditionExpression y FilterExpression — los atributos de clave en el filtro son un error habitual al copiar y pegar desde código de Scan.

Ejecútalo en DynoTable

El panel de consultas de DynoTable mantiene las condiciones de clave y los filtros en campos separados — las restricciones sobre la clave de partición y de ordenación nunca acaban en FilterExpression. Abre una tabla con ⌘K, define la condición de clave y añade después los filtros que no son de clave; copia la petición generada a tu SDK.

Usa el Query Builder para prototipar consultas sobre GSI donde las claves del índice deben quedarse en KeyConditionExpression. Cambia de perfil con ⌘P; Test Connection en Ajustes → Perfiles confirma que el índice existe. Consulta Conectar a AWS e Instalar.

Fuentes

Query — Amazon DynamoDB API Reference (verificado 2026-07-13)
Filter expressions for Query (verificado 2026-07-13)

Errores relacionados

Query key condition not supported — un operador/forma inválidos en la propia condición de clave.
Query condition missed key schema element — la consulta no proporcionó la clave de partición.
Ejemplo de código: Query en Node.js — condición de clave y filtro separados correctamente.
Aprende: Estrategias de filtrado · Expresiones de condición de clave

Referencias

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