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

> 페이지 번호를 0이나 음수로 받으면 (page-1)*size 계산이 음수 OFFSET을 만들어 PostgreSQL이 쿼리를 거부하고 목록 API가 500을 반환한다. 원인과, 페이지 번호를 서버에서 유효 범위로 보정하는 해결을 정리한다.

- Source: https://jiny-log.vercel.app/ko/posts/postgresql-offset-must-not-be-negative
- Markdown: https://jiny-log.vercel.app/posts/ko/postgresql-offset-must-not-be-negative.md
- Published: 2026-09-27
- Category: troubleshooting
- Tags: postgresql, pagination, spring-boot, jpa, sql
- Language: ko

**TL;DR** 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이 뱉은 다음 에러가 남는다.

```text
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을 직접 음수로 넣으면 프레임워크와 무관하게 같은 에러가 난다.

```sql
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"](https://www.postgresql.org/docs/current/queries-limit.html)).

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

## 해결

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

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

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

```jsonc
// 응답
{
  "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) 페이지네이션을 검토한다.