"Local secondary indexes must be specified at table creation": los índices secundarios locales deben especificarse en la creación de la tabla

TL;DR: un índice secundario local (LSI) solo se puede crear en el momento en que se crea su tabla; no se puede agregar, cambiar ni eliminar posteriormente. UpdateTable no tiene operación durante LSIs, por lo que cualquier intento de agregar uno a una tabla activa falla la validación. Para obtener un nuevo LSI, debe crear una nueva tabla (con el LSI) y migrar los datos, o usar un índice secundario global (GSI), que puede agregarse en línea.

Qué significa

ValidationException: One or more parameter values were invalid: Local secondary
indexes can only be created when a table is created

Un LSI comparte su clave de partición con la tabla base y añade una clave de ordenación alternativa; DynamoDB lo co-ubica con la partición del item en el momento de la escritura. Debido a ese acoplamiento físico, un LSI debe existir desde la primera escritura de la tabla — UpdateTable admite añadir/quitar GSI pero no tiene ningún parámetro de LSI en absoluto, así que no existe ninguna petición que siquiera pudieras enviar para incorporarlo a posteriori. El mensaje exacto varía según la ruta (una llamada del SDK/CLI puede fallar la validación de parámetros del lado del cliente; las herramientas de IaC muestran su propia redacción), pero la forma del lado del servicio es un HTTP 400 ValidationException y no es reintentable: la operación simplemente no está soportada sobre una tabla existente.

Por qué ocurre

Añadir un LSI a una tabla en producción — llamar a UpdateTable (o editar una plantilla de CloudFormation/Terraform) para introducir una nueva entrada LocalSecondaryIndexes en una tabla que ya existe.
Cambiar un LSI existente — su esquema de clave o su proyección están fijados en la creación; las ediciones se rechazan.
Un diff de IaC que recrea en vez de actualizar — la herramienta intenta actualizar-en-el-sitio un cambio de LSI que DynamoDB solo permite en el momento de la creación.

Cómo solucionarlo

Crea una tabla nueva con el LSI definido por adelantado, luego migra los datos (scan-y-escribir, o un export/import bajo demanda).

Usa un GSI en su lugar si el patrón de acceso lo permite — los GSI se pueden añadir a una tabla existente en línea y no requieren la misma clave de partición:

aws dynamodb update-table --table-name <Table> \
  --attribute-definitions AttributeName=gsi_sk,AttributeType=S \
  --global-secondary-index-updates '[{"Create":{"IndexName":"gsi1", ...}}]'

Planifica los LSI durante el modelado — decide las claves de ordenación alternativas antes de que exista la tabla, ya que no se pueden incorporar a posteriori.
Modela primero el patrón de acceso en un GSI. Si la consulta funciona sobre un GSI con otra clave de partición, te ahorras por completo reconstruir la tabla.

Mide el tamaño en DynoTable

Antes de reconstruir una tabla por un LSI, valida el patrón de acceso en DynoTable — abre la tabla con ⌘K y prueba si una consulta sobre un GSI cubre la misma necesidad. El Query Builder genera el KeyConditionExpression que tu nuevo índice debe servir.

Usa la calculadora de precios para comparar la amplificación de escritura de un LSI frente a la alternativa con GSI. Cambia de perfil con ⌘P; consulta Conectar con AWS e Instalación.

Fuentes

Local secondary indexes (verificado 2026-07-13)
UpdateTable — Amazon DynamoDB API Reference (verificado 2026-07-13)

Errores relacionados

Attempting to modify a GSI that is being created — un cambio de GSI bloqueado mientras el índice se construye.
Requested resource not found / index not found — consultar un nombre de índice que no existe.
ValidationException (visión general)
Aprende: GSI vs LSI · Índices

Referencias

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