"Segment must be less than TotalSegments": o segmento deve ser menor que TotalSegments

TL;DR — Em uma varredura paralela, cada trabalhador define Segment (seu índice de fatia) e TotalSegments (quantas fatias). DynamoDB requer 0 ≤ Segment < TotalSegments e ambos devem ser fornecidos juntos. Um Segment igual ou superior a TotalSegments é rejeitado. Atribua a cada trabalhador um Segment distinto de 0 a TotalSegments − 1.

O que 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

Uma varredura paralela divide a tabela em fatias TotalSegments; cada trabalhador verifica uma fatia identificada por Segment. Os valores válidos de Segment são de 0 a TotalSegments − 1. O próprio TotalSegments deve estar entre 1 e 1,000,000. Se você fornecer um sem o outro, ou um Segment fora do alcance, o DynamoDB rejeitará a chamada. É um HTTP 400 ValidationException, do lado do cliente e não pode ser repetido até que os parâmetros sejam válidos.

Por que isso acontece

• Atribuição de segmento off-by-one — com TotalSegments = 4, usando valores Segment 1..4 em vez de 0..3.
• Segment ≥ TotalSegments — um índice de trabalho que atende ou excede a contagem de fatias.
• Apenas um do par fornecido — passando Segment sem TotalSegments (ou vice-versa); ambos são necessários para uma varredura paralela.
• Uma incompatibilidade dinâmica de pool de trabalhadores — TotalSegments definido como um valor diferente do número de trabalhadores realmente iniciados, portanto, alguns trabalhadores obtêm índices fora do intervalo.

Como corrigir

1. Atribuir segmentos 0 a TotalSegments − 1 — um Segment distinto por trabalhador.
2. Sempre passe ambos os parâmetros juntos em cada solicitação de varredura paralela.
3. Mantenha TotalSegments igual à contagem de trabalhadores e dentro de 1..1,000,000 (um TotalSegments de 1 é apenas uma varredura sequencial).
4. Use indexação baseada em zero ao mapear o ordinal de um trabalhador para seu Segment.
5. Registre ambos os parâmetros em cada trabalhador. Quando uma frota falha, a mensagem de erro nomeia o Segment e o TotalSegments ofensivos — compare-os com o que cada processo realmente enviou.

Exemplo

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

No DynoTable

Antes de paralelizar uma varredura em produção, execute uma varredura de segmento único no DynoTable para confirmar se a tabela e o filtro se comportam conforme o esperado. Abra a tabela com ⌘K, execute uma varredura no painel de consulta e inspecione os itens retornados – você verá os dados que cada segmento tocaria sem lançar uma frota de trabalhadores.

Ao mover o Scan para o código, crie um protótipo da solicitação no Query Builder — ele emite Segment e TotalSegments junto com os parâmetros completos do Scan. A troca de perfil (⌘P) e Testar conexão em Configurações → Perfis mantêm os trabalhadores apontados para a conta certa. Consulte Conectar ao AWS e Instalar. Lembre-se de que os segmentos são baseados em zero: com quatro trabalhadores, os valores válidos são 0, 1, 2 e 3 — não de 1 a 4. A atribuição de segmento off-by-one é a causa mais comum quando a contagem de trabalhadores e TotalSegments correspondem, mas um trabalhador ainda falha.

Fontes

• Digitalizar - Referência Amazon DynamoDB API (verificado em 13/07/2026)
• Verificando tabelas em DynamoDB (verificado em 13/07/2026)

Erros relacionados

• Condição da chave de consulta não suportada — um erro de validação de expressão de consulta/verificação relacionado.
• A expressão de filtro só pode conter atributos de chave não primários — um atributo de chave usado incorretamente em um filtro de verificação/consulta.
• ValidationException (visão geral) Aprenda: Varreduras paralelas

Referências

• Digitalizar - Referência Amazon DynamoDB API
• Verificação de tabelas no DynamoDB (varredura paralela) — Guia do desenvolvedor do Amazon DynamoDB
• Tratamento de erros com DynamoDB — Guia do desenvolvedor do Amazon DynamoDB

Última verificação em 13/07/2026 em relação à documentação oficial do AWS vinculada acima.