Next.js 서버 액션 This page couldn't load 원인

먼저 결론
증상: 웹 화면에서 짧은 입력은 되는데 긴 입력을 넣으면 "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일에 마지막으로 확인했습니다. 틀린 곳을 발견하시면 연락처로 알려 주세요.