Segment must be less than TotalSegments

TL;DR — In einem parallelen Scan setzt jeder Worker Segment (seinen Slice-Index) und TotalSegments (die Anzahl der Slices). DynamoDB verlangt 0 ≤ Segment < TotalSegments, und beide müssen zusammen übergeben werden. Ein Segment gleich oder größer TotalSegments wird abgelehnt. Gib jedem Worker ein eigenes Segment von 0 bis TotalSegments − 1.

Was es bedeutet

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

Ein paralleler Scan teilt die Tabelle in TotalSegments Slices; jeder Worker scannt einen durch Segment identifizierten Slice. Gültige Segment-Werte sind 0 bis TotalSegments − 1. TotalSegments selbst muss zwischen 1 und 1.000.000 liegen. Wenn du das eine ohne das andere übergibst oder ein Segment außerhalb des Bereichs, lehnt DynamoDB den Aufruf ab. Es ist eine HTTP-400-ValidationException, clientseitig, und nicht wiederholbar, bis die Parameter gültig sind.

Warum es passiert

Off-by-one bei der Segmentzuweisung — bei TotalSegments = 4 Segment-Werte 1..4 statt 0..3 verwenden.
Segment ≥ TotalSegments — ein Worker-Index, der die Slice-Anzahl erreicht oder überschreitet.
Nur eines des Paares übergeben — Segment ohne TotalSegments (oder umgekehrt) übergeben; beide sind für einen parallelen Scan erforderlich.
Ein Konflikt beim dynamischen Worker-Pool — TotalSegments auf einen anderen Wert gesetzt als die tatsächlich gestartete Anzahl von Workern, sodass einige Worker außerhalb des Bereichs liegende Indizes bekommen.

So behebst du es

Weise Segmente 0 bis TotalSegments − 1 zu — ein eindeutiges Segment pro Worker.
Übergib immer beide Parameter gemeinsam bei jedem Parallel-Scan-Request.
Halte TotalSegments gleich der Worker-Anzahl und innerhalb von 1..1.000.000 (ein TotalSegments von 1 ist einfach ein sequenzieller Scan).
Nutze nullbasierte Indizierung, wenn du die Ordinalzahl eines Workers auf sein Segment abbildest.
Logge beide Parameter in jedem Worker. Scheitert eine Flotte, nennt die Fehlermeldung das schuldige Segment und TotalSegments — vergleiche sie mit dem, was jeder Prozess tatsächlich gesendet hat.

Beispiel

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

In DynoTable

Bevor du einen Scan in der Produktion parallelisierst, führe in DynoTable einen Scan mit einem einzigen Segment aus, um zu bestätigen, dass Tabelle und Filter sich wie erwartet verhalten. Öffne die Tabelle mit ⌘K, starte einen Scan aus dem Query-Panel und sieh dir die zurückgegebenen Items an — so siehst du die Daten, die jedes Segment berühren würde, ohne eine Worker-Flotte zu starten.

Wenn du den Scan in Code überführst, prototype den Request im Query Builder — er gibt Segment und TotalSegments zusammen mit den vollständigen Scan-Parametern aus. Profilwechsel (⌘P) und Verbindung testen unter Einstellungen → Profile halten die Worker auf dem richtigen Konto. Siehe Mit AWS verbinden und Installation. Denk daran, dass Segmente nullbasiert sind: bei vier Workern sind 0, 1, 2 und 3 gültig — nicht 1 bis 4. Eine Off-by-one-Segmentzuweisung ist die häufigste Ursache, wenn Worker-Anzahl und TotalSegments übereinstimmen, aber trotzdem ein Worker scheitert.

Quellen

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

Referenzen

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.