"Segment must be less than TotalSegments" — 세그먼트는 TotalSegments보다 작아야 합니다.

TL;DR — 병렬 스캔에서 각 작업자는 Segment(슬라이스 인덱스) 및 TotalSegments(슬라이스 수)를 설정합니다. DynamoDB에는 0 ≤ Segment < TotalSegments가 필요하며 둘 다 함께 제공되어야 합니다. TotalSegments 이상인 Segment는 기각됩니다. 각 근로자에게 0부터 TotalSegments − 1까지 고유한 Segment를 할당합니다.

무엇을 의미하는가

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

병렬 스캔은 테이블을 TotalSegments개의 조각으로 나눕니다. 각 작업자는 Segment로 식별된 하나의 슬라이스를 스캔합니다. 유효한 Segment 값은 0부터 TotalSegments − 1까지입니다. TotalSegments 자체는 1에서 1,000,000 사이여야 합니다. 하나만 제공하거나 범위를 벗어나는 Segment을 제공하면 DynamoDB는 호출을 거부합니다. HTTP 400 ValidationException으로, 클라이언트 측이며 매개변수가 유효할 때까지 재시도할 수 없습니다.

왜 발생하는가

Off-by-one 세그먼트 할당 — TotalSegments = 4에서 0..3 대신 Segment 값 1..4를 사용합니다.
Segment ≥ TotalSegments — 조각 수를 충족하거나 초과하는 작업자 인덱스입니다.
제공된 쌍 중 하나만 — TotalSegments 없이 Segment를 전달합니다(또는 그 반대로). 병렬 스캔에는 둘 다 필요합니다.
동적 작업자 풀 불일치 — TotalSegments가 실제로 시작된 작업자 수와 다른 값으로 설정되어 일부 작업자의 지수가 범위를 벗어났습니다.

어떻게 해결하는가

세그먼트 0 ~ TotalSegments − 1를 할당합니다 — 근로자당 하나의 고유한 Segment.
모든 병렬 스캔 요청에서 항상 두 매개변수를 함께 전달합니다.
TotalSegments을 작업자 수와 동일하게 유지하고 1..1,000,000 이내로 유지합니다(1의 TotalSegments는 순차 스캔일 뿐입니다).
작업자의 서수를 Segment에 매핑할 때 0부터 시작하는 인덱싱을 사용합니다.
모든 작업자에 대해 두 매개변수를 모두 기록합니다. 플릿이 실패하면 오류 메시지에 문제의 이름이 Segment 및 TotalSegments로 지정됩니다. 이를 각 프로세스가 실제로 보낸 것과 비교합니다.

예제

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

DynoTable에서

프로덕션에서 스캔을 병렬화하기 전에 DynoTable에서 단일 세그먼트 스캔을 실행하여 테이블과 필터가 예상대로 작동하는지 확인하세요. ⌘K로 테이블을 열고, 쿼리 패널에서 스캔을 실행하고, 반환된 항목을 검사합니다. 작업자 플릿을 시작하지 않고도 각 세그먼트가 처리할 데이터를 볼 수 있습니다.

Scan을 코드로 이동할 때 Query Builder에 요청의 프로토타입을 생성합니다. 전체 Scan 매개변수와 함께 Segment 및 TotalSegments을 방출합니다. 설정의 프로필 전환(⌘P) 및 연결 테스트 → 프로필을 통해 작업자가 올바른 계정을 계속 가리키게 됩니다. Connect to AWS 및 Install를 참조하세요. 세그먼트는 0부터 시작합니다. 작업자가 4개인 경우 유효한 값은 1부터 4까지가 아닌 0, 1, 2, 3입니다. 작업자 수와 TotalSegments가 일치하지만 작업자 한 명이 여전히 실패할 때 가장 일반적인 원인은 하나를 벗어난 세그먼트 할당입니다.

출처

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

참고 자료

위에 링크된 공식 AWS 문서를 기준으로 2026년 7월 13일에 마지막으로 확인되었습니다.