트러블슈팅
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 또는 음수에서만 재현된다.
재현 환경
| 항목 | 값 |
|---|---|
| DB | PostgreSQL — 음수 OFFSET 거부는 특정 버전이 아니라 전 버전 공통 동작 |
| 쿼리 계층 | offset = (page - 1) * pageSize 로 offset 생성 (Spring Data JPA Pageable 포함, 원리는 동일) |
| pageSize | 15 |
| 확인일 | 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) 페이지네이션을 검토한다.