증상: 웹 화면에서 짧은 입력은 되는데 긴 입력을 넣으면 "This page couldn't load" 로 화면이 죽었습니다. 15자, 69자는 성공, 120자는 3번 모두 실패였습니다.
원인: 서버 액션은 응답에 그 페이지를 다시 그린 데이터를 통째로 싣습니다. 일하는 시간 11초에 큰 페이지 다시 그리기가 겹쳐 함수 시간 한계를 넘겼습니다.
해결: 일을
src/app/api/.../route.ts 전용 길로 빼고 화면은 fetch 로 불렀습니다. 더 나은 길은 번호표만 주고 끝내는 방식입니다.Next.js 로 만든 웹 화면에 입력 상자 하나가 있었습니다. 글을 넣고 단추를 누르면 서버가 오래 걸리는 생성 작업을 하고 결과를 돌려주는 구조였습니다. 시험할 때 넣은 짧은 문장은 늘 됐는데, 긴 문장을 넣자 화면 전체가 오류 페이지로 바뀌었습니다.
경계부터 찾았다
무엇이 원인인지 모를 때는 되는 것과 안 되는 것의 경계부터 찾습니다. 입력 길이를 바꿔 가며 눌러 봤습니다.
| 입력 | 결과 |
|---|---|
| 15자 | 성공 |
| 69자 | 성공 |
| 120자 | "This page couldn't load", 3회 모두 같음 |
| 120자를 백엔드에 직접 보냄 | 11.2초에 성공 |
마지막 줄이 방향을 정했습니다. 같은 문장을 화면을 거치지 않고 백엔드에 직접 보내면 11.2초 만에 멀쩡히 결과가 나왔습니다. 작업을 하는 엔진이 아니라, 화면이 그 작업을 부르는 방식이 문제라는 뜻입니다.
엔진이 아니라 부르는 방식
그 입력 상자는 서버 액션으로 서버 함수를 불렀습니다. 서버 액션은 편하지만, 응답에 결과만 싣는 것이 아니라 그 페이지를 다시 그린 데이터를 통째로 실어 보냅니다.
하필 그 상자가 붙은 페이지는 1,000줄이 넘는 큰 페이지였고, 빌드 결과에 ƒ Dynamic 으로 찍히는, 매 요청마다 새로 그리는 페이지였습니다. 그래서 한 요청 안에 일하는 시간 11초와 페이지 전체를 다시 그리는 시간이 겹쳤고, 합이 함수 시간 한계를 넘겼습니다. 관찰로는 10초 근처가 벽이었습니다.
짧은 입력은 일하는 시간이 짧아 벽 안에 들어왔고, 120자는 벽을 넘었습니다. 길이가 원인처럼 보였지만 실제로는 시간이 원인이었습니다.
전용 길로 뺀 코드
오래 걸리는 일은 페이지와 떨어진 전용 길로 옮겼습니다. App Router 의 route 파일입니다.
// src/app/api/generate/route.ts
export const dynamic = 'force-dynamic'
export const maxDuration = 60
export async function POST(req: Request) {
const { text } = await req.json()
const result = await runLongJob(text)
return Response.json({ ok: true, result })
}
우리가 쓰던 호스팅에서는 여기서 maxDuration = 60 이 확실히 먹었습니다. 오가는 것이 작은 JSON 하나라 페이지를 다시 그리지 않기 때문입니다. 다만 이 값은 서버리스 호스팅의 함수 시간 설정이라 호스팅과 요금제에 따라 상한이 다르고, 직접 띄운 노드 서버에서는 뜻이 없습니다. 화면 쪽은 useActionState 를 걷어 내고 fetch 로 불렀습니다.
const r = await fetch('/api/generate', { method: 'POST', body: JSON.stringify({ text }) })
const res = await r.json()
if (!r.ok || res.ok !== true) showError()
마지막 줄처럼 상태 코드와 성공 표시를 둘 다 보는 이유는 fetch 가 403 을 성공으로 넘길 때에 따로 적었습니다.
새 길을 배포한 뒤에는 화면을 거치지 않고 curl 로 그 길을 직접 불러 보면 엔진과 화면 중 어느 쪽 문제인지 빨리 가를 수 있습니다. 이때 흔히 저지르는 실수는 curl 로 라이브 반영을 확인할 때 저지른 세 가지 실수에, 배포했는데 화면이 옛 파일을 계속 부르는 경우는 파일을 고쳤는데 옛 파일이 계속 보일 때 캐시 점검에 적었습니다.
번호표 방식이 더 낫다
전용 길로 빼면 시간 한계가 넉넉해질 뿐, 요청 하나가 일이 끝날 때까지 붙들려 있는 것은 그대로입니다. 더 나은 구조는 요청을 받자마자 번호표만 주고 끝내는 것입니다. 화면은 그 번호표로 "다 됐나"를 몇 초마다 물어봅니다. 길은 두 개로 나눕니다.
// src/app/api/jobs/route.ts : 일을 맡기고 번호표만 돌려준다
export async function POST(req: Request) {
const { text } = await req.json()
const id = await enqueueJob(text) // 대기열에 넣기만 한다
return Response.json({ ok: true, id })
}
// src/app/api/jobs/[id]/route.ts : 번호표로 진행을 묻는다
export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
const { id } = await params
const job = await getJob(id) // { state: 'running' | 'done', result? }
return Response.json({ ok: true, ...job })
}
요점은 실제 일이 이 함수 밖에서 돈다는 것입니다. 서버리스 함수는 응답을 보내면 끝나므로, 일을 계속할 작업 대기열이나 별도 작업 서버가 따로 있어야 합니다. 우리가 그 일을 어디서 돌렸는지는 이 글에서 다루지 않습니다.
| 방식 | 함수가 붙들린 시간 | 화면이 하는 일 |
|---|---|---|
| 서버 액션 | 일하는 시간 + 페이지 다시 그리기 | 응답을 기다림, 120자에서 죽음 |
| 전용 route | 일하는 시간(11초 안팎) | 응답을 기다림 |
| 번호표 | 1.3초 | 번호표로 진행을 물음 |
번호표 방식으로 바꾸자 함수가 붙들린 시간이 11초에서 1.3초로 줄었습니다. 시간 제한 문제가 뿌리째 사라진 셈입니다. 원격 서버에서 긴 일을 뒤에 돌려 두고 끝났는지 따로 확인하는 것도 같은 생각이며, 그 함정은 ssh nohup 과 완료 감시 함정에 적었습니다.
실패 안내 문구도 고쳐야 한다
놓치기 쉬운 점이 하나 더 있었습니다. 화면이 죽었을 때도 서버는 결과를 다 만들었고, 사용 횟수도 세어졌습니다. 사용자 눈에는 "실패했는데 횟수만 줄었다"로 보입니다.
그래서 안내 문구는 이 점을 감안해 짜야 합니다. 예를 들어 오류를 받았다고 바로 "실패했습니다, 다시 시도하세요"라고만 쓰면, 사용자는 다시 눌러 같은 일을 한 번 더 시키게 됩니다. 오래 걸리는 일을 다루는 화면은 실패해도 일은 이미 벌어져 있을 수 있다고 보고, 결과가 만들어졌는지 먼저 확인하게 이끄는 편이 낫습니다.
확인한 환경
| 항목 | 내용 |
|---|---|
| 프레임워크 | Next.js, 서버 액션과 useActionState 에서 route 로 옮김 |
| 페이지 | 1,000줄 넘는 ƒ Dynamic 페이지 |
| 재현 | 120자 3회 실패, 직접 호출 11.2초 성공 |
| 확인한 시기 | 2026년 8월 31일에서 9월 1일 |
이 글의 내용은 2026년 10월 27일에 마지막으로 확인했습니다. 틀린 곳을 발견하시면 연락처로 알려 주세요.