"Segment must be less than TotalSegments": el segmento debe ser menor que TotalSegments

TL;DR: en un Scan paralelo, cada trabajador establece Segment (su índice de sector) y TotalSegments (cuántos sectores). DynamoDB requiere 0 ≤ Segment < TotalSegments, y ambos deben suministrarse juntos. Se rechaza un Segment igual o superior a TotalSegments. Asigne a cada trabajador un Segment distinto de 0 a TotalSegments − 1.

Qué significa

ValidationException: The Segment parameter is zero-based and must be less than parameter TotalSegments: Segment: 5 is not less than TotalSegments: 2

# on DynamoDB Local the same call reports the constraint generically instead:
ValidationException: 1 validation error detected: Value '5' at 'segment' failed to satisfy constraint: Member must have value less than or equal to 1

Un scan paralelo divide la tabla en TotalSegments porciones; cada worker escanea una porción identificada por Segment. Los valores válidos de Segment van de 0 a TotalSegments − 1. El propio TotalSegments debe estar entre 1 y 1.000.000. Si suministras uno sin el otro, o un Segment fuera del rango, DynamoDB rechaza la llamada. Es un ValidationException HTTP 400, del lado del cliente, y no es reintentable hasta que los parámetros sean válidos.

Por qué ocurre

• Asignación de segmentos con desfase de uno (off-by-one) — con TotalSegments = 4, usar valores de Segment 1..4 en lugar de 0..3.
• Segment ≥ TotalSegments — un índice de worker que iguala o supera el número de porciones.
• Solo se suministra uno del par — pasar Segment sin TotalSegments (o viceversa); ambos son necesarios para un scan paralelo.
• Un desajuste de un pool dinámico de workers — TotalSegments fijado a un valor distinto del número de workers realmente lanzados, así que algunos workers reciben índices fuera de rango.

Cómo solucionarlo

1. Asigna segmentos de 0 a TotalSegments − 1 — un Segment distinto por worker.
2. Pasa siempre ambos parámetros juntos en cada petición de scan paralelo.
3. Mantén TotalSegments igual al número de workers y dentro de 1..1.000.000 (un TotalSegments de 1 es simplemente un scan secuencial).
4. Usa indexación basada en cero al mapear el ordinal de un worker a su Segment.
5. Registra ambos parámetros en cada worker. Cuando falla una flota, el mensaje de error nombra el Segment y el TotalSegments culpables — compáralos con lo que cada proceso envió realmente.

Ejemplo

const totalSegments = workers.length;
await Promise.all(
  workers.map((_, segment) =>
    doc.send(
      new ScanCommand({
        TableName: 'Orders',
        Segment: segment, // 0 .. totalSegments - 1
        TotalSegments: totalSegments
      })
    )
  )
);

En DynoTable

Antes de paralelizar un Scan en producción, ejecuta un Scan de un solo segmento en DynoTable para confirmar que la tabla y el filtro se comportan como esperas. Abre la tabla con ⌘K, lanza un Scan desde el panel de consulta e inspecciona los ítems devueltos — ves los datos que tocaría cada segmento sin arrancar una flota de workers.

Cuando lleves el Scan al código, prototipa la petición en el Query Builder — emite Segment y TotalSegments junto al resto de parámetros del Scan. El cambio de perfil (⌘P) y Test Connection en Ajustes → Perfiles mantienen a los workers apuntando a la cuenta correcta. Consulta Conectar a AWS e Instalar. Recuerda que los segmentos empiezan en cero: con cuatro workers, los valores válidos son 0, 1, 2 y 3 — no del 1 al 4. El desfase de uno en la asignación de segmentos es la causa más común cuando el número de workers y TotalSegments coinciden pero un worker sigue fallando.

Fuentes

• Scan — Amazon DynamoDB API Reference (verificado 2026-07-13)
• Scanning tables in DynamoDB (verificado 2026-07-13)

Errores relacionados

• Query key condition not supported — un error de validación de expresión de Query/Scan relacionado.
• Filter Expression can only contain non-primary key attributes — un atributo de clave usado por error en un filtro de Scan/Query.
• ValidationException (descripción general)
• Aprende: Parallel scans

Referencias

• Scan — Amazon DynamoDB API Reference
• Scanning tables in DynamoDB (Parallel scan) — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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