지니로그

트러블슈팅

PostgreSQL에서 OFFSET이 음수면 'must not be negative'로 쿼리가 실패한다

이 글은 한국어로만 있습니다

OFFSET에 음수가 들어가면 PostgreSQL은 `ERROR: OFFSET must not be negative`로 쿼리를 거부한다. 페이지네이션에서 offset을 `(page-1)*pageSize`로 만들 때 page가 0이나 음수면 offset이 음수가 되는 것이 원인이다. 클라이언트 입력을 믿지 말고 서버에서 page를 [1, maxPage]로 clamp한 뒤 offset을 계산하고, 보정된 page를 응답에 실어 준다.

증상

목록 조회 API에 ?page=0 을 주면 200이 아니라 500이 떨어진다. 서버 로그에는 PostgreSQL이 뱉은 다음 에러가 남는다.

ERROR:  OFFSET must not be negative

page=1 이상은 정상이고, page=0 또는 음수에서만 재현된다.

재현 환경

항목값
DBPostgreSQL — 음수 OFFSET 거부는 특정 버전이 아니라 전 버전 공통 동작
쿼리 계층offset = (page - 1) * pageSize 로 offset 생성 (Spring Data JPA Pageable 포함, 원리는 동일)
pageSize15
확인일2026-09-27

재현 방법

offset을 직접 음수로 넣으면 프레임워크와 무관하게 같은 에러가 난다.

SELECT * FROM notice ORDER BY notice_id DESC LIMIT 15 OFFSET -15;
-- ERROR:  OFFSET must not be negative

page 로부터 offset을 만드는 코드가 (page - 1) * pageSize 라면, page=0 은 (0 - 1) * 15 = -15 가 되어 위 쿼리와 같아진다.

왜 이 에러가 나는가

OFFSET은 “결과에서 건너뛸 행 수”라서 음수가 정의되지 않고, PostgreSQL은 이를 조용히 0으로 바꾸지 않고 쿼리 자체를 거부한다. PostgreSQL 공식 문서의 LIMIT and OFFSET 절이 “OFFSET은 음수일 수 없다”고 명시한다 (PostgreSQL Documentation, “LIMIT and OFFSET”).

문제의 뿌리는 DB가 아니라 입력 검증 위치다. page 가 사용자·크롤러·오래된 링크에서 그대로 넘어오는데, offset 계산식이 page >= 1 을 암묵적으로 가정하고 있었다. 가정이 깨지는 입력(0, 음수)이 그대로 SQL까지 도달한 것이다.

해결

offset을 만들기 전에 서버에서 page 를 유효 범위로 clamp한다. 프론트가 아니라 DB에 가장 가까운 서버 계층에서 막는다.

// page 는 신뢰할 수 없는 입력이다. offset 을 만들기 전에 범위를 강제한다.
const safePage = Math.min(Math.max(page, 1), maxPage);
const offset = (safePage - 1) * pageSize;

보정한 page 는 응답에도 실어 준다. 그래야 프론트 페이저가 요청값이 아니라 실제로 조회된 페이지를 강조한다.

// 응답
{
  "page": 1,          // 서버가 [1, maxPage] 로 clamp 한 실제 페이지
  "maxPage": 5,
  "totalCount": 62,
  "list": [ /* ... */ ]
}

여러 방어 지점의 트레이드오프:

방어 위치잘못된 page 차단한계
프론트 입력 UI일부직접 호출·북마크·크롤러는 못 막는다
서버 clamp차단없음 — 유일하게 확실한 지점
DB(그대로 전달)못 막음음수 OFFSET → 500

왜 이 해결이 맞는가

증상은 500이지만 원인은 “신뢰할 수 없는 입력을 검증 없이 SQL까지 흘려보낸 것”이므로, 500을 try/catch로 삼키는 것은 오답이다. ?page=0 은 사용자 실수만이 아니라 오래된 링크·크롤러·수기 호출로도 들어온다. 경계값 보정을 서버에 두면 이 모든 경로가 한 곳에서 정상 응답(1페이지)으로 수렴한다.

보정된 page를 응답에 싣는 것까지가 해결의 일부다. 이걸 빼면 목록은 1페이지를 보여주는데 페이저는 0을 강조하는, 데이터와 UI가 어긋난 상태가 된다.

이것도 확인해볼 것

  • page 가 maxPage 를 초과할 때: 빈 결과를 줄지 마지막 페이지로 clamp할지 정책을 정한다. 위 예시는 마지막 페이지로 clamp한다.
  • LIMIT 이 0이나 음수로 들어오는 경로: LIMIT도 음수면 같은 계열의 에러가 난다.
  • offset이 큰 딥 페이지네이션의 성능: 수십만 행 뒤로 갈수록 OFFSET 은 느려진다. 무한 스크롤·정렬 키 기반이라면 keyset(cursor) 페이지네이션을 검토한다.