[Vercel][운영] FUNCTION_INVOCATION_TIMEOUT이 날 때 maxDuration과 Runtime Logs를 같이 보는 순서

IT 리서치 노트

[Vercel][운영] FUNCTION_INVOCATION_TIMEOUT이 날 때 maxDuration과 Runtime Logs를 같이 보는 순서

Vercel에서 504 FUNCTION_INVOCATION_TIMEOUT이 뜨면 많은 팀이 먼저 maxDuration만 늘린다. 하지만 2026년 6월 26일 기준 Vercel 공식 문서를 다시 보면 timeout은 함수 상한 자체, 응답을 끝내지 못한 코드 경로, 외부 API나 DB 대기, region과 memory 설정이 함께 얽혀 생긴다. 그래서 이 에러는 maxDuration과 Runtime Logs를 같이 봐야 빨리 좁혀진다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 FUNCTION_INVOCATION_TIMEOUT은 maxDuration 설정 하나로만 풀리는 문제가 아니다. 현재 플랜과 함수 상한을 먼저 확인하고, Runtime Logs에서 실제로 어떤 요청이 오래 걸렸는지 본 다음, 외부 의존성 대기인지 코드 경로 문제인지 나눠 봐야 한다.

이미 Vercel duration과 memory 글을 읽었다면 이번 글은 운영 단계다. 실제 timeout이 났을 때 설정을 늘릴지, 로그 기준으로 병목을 고칠지 판단하는 순서를 다룬다.

2. 어디서 실제로 막히는가

가장 흔한 오해는 timeout을 모두 'duration이 짧아서 생긴다'로 보는 것이다. 실제로는 함수가 응답을 반환하지 않거나, upstream API가 너무 느리거나, DB region이 멀어 대기가 길거나, memory 부족으로 CPU가 느려진 경우도 timeout으로 같은 504를 낸다. 그래서 maxDuration만 늘리면 증상은 늦게 나타나지만 원인은 그대로 남는다.

또 build logs와 runtime logs를 섞어 보면 시간만 길어진다. timeout은 배포가 성공했더라도 runtime request에서만 드러나는 문제라서, 어떤 route가 어느 deployment에서 반복적으로 느렸는지를 runtime logs로 먼저 좁혀야 한다.

• 증상: 504 FUNCTION_INVOCATION_TIMEOUT이 간헐적으로 반복된다.
• 실패: maxDuration만 늘리고 runtime logs는 보지 않는다.
• 막힘: build logs가 깨끗하니 함수 문제도 아닐 것이라 착각한다.
• 누락: region mismatch, memory 부족, 외부 API 대기를 같은 timeout으로 묶어 본다.

증상	먼저 볼 곳	판단 기준
모든 요청이 비슷하게 timeout	plan limit과 maxDuration	상한 자체가 작업 시간보다 짧은지 본다
특정 route만 timeout	Runtime Logs와 upstream 호출	API 대기나 DB 쿼리 지연이 긴지 본다
배포 직후에만 느리다	deployment별 로그와 cold path	초기화 비용인지 지속 병목인지 나눈다

3. 실무에서 적용하는 순서

가장 빠른 확인 순서는 다섯 단계다. 첫째, 현재 플랜과 함수의 maxDuration 상한을 확인한다. 둘째, Runtime Logs에서 timeout이 난 route와 deployment를 찾는다. 셋째, 요청이 어디서 오래 멈췄는지 upstream API, DB, region, memory 관점으로 본다. 넷째, 작업 자체가 정상적으로 길다면 maxDuration이나 Fluid Compute를 조정한다. 마지막으로 무한 대기나 응답 미반환 패턴이면 코드와 외부 의존성을 먼저 고친다.

1. plan limit과 함수 maxDuration을 먼저 확인한다.
2. Runtime Logs에서 timeout route와 deployment를 찾는다.
3. upstream API, DB, region, memory 병목을 나눠 본다.
4. 정상 장기 작업이면 설정을 늘린다.
5. 무한 대기나 응답 누락이면 코드 흐름을 먼저 고친다.

운영 메모 예시

route: /api/report
deployment: prod-2026-06-26-01
timeout_code: FUNCTION_INVOCATION_TIMEOUT
max_duration_seconds: 60
upstream_wait_ms: 54000
region: icn1
action: inspect upstream API before raising maxDuration

이 메모를 남기면 timeout 대응이 설정 조정인지 병목 수정인지 빠르게 갈린다. 예를 들어 upstream_wait_ms가 대부분을 차지하면 maxDuration보다 외부 API 대기부터 줄여야 한다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 Vercel의 FUNCTION_INVOCATION_TIMEOUT 에러 페이지다. 여기서는 timeout이 단순히 코드가 느리다는 뜻이 아니라, 허용된 실행 시간 안에 응답을 못 돌려줬다는 뜻임을 먼저 분명하게 잡아 준다.

Vercel 에러 문서는 FUNCTION_INVOCATION_TIMEOUT을 허용 실행 시간 초과로 정의한다.

즉 이 에러는 DB나 외부 API가 느리든, 코드가 응답을 반환하지 않든, 무한 루프가 있든 결국 응답 완료 시간 초과라는 한 지점으로 모인다. 그래서 첫 단계는 에러 문구 자체보다 실행 시간과 로그를 같이 보는 것이다.

두 번째 자료는 functions limits 문서의 max duration 구간이다. plan별 기본값과 최대값을 먼저 봐야 현재 timeout이 설정 부족인지, 코드/IO 병목인지 판단할 수 있다.

Functions limits 문서는 max duration 초과 시 504 FUNCTION_INVOCATION_TIMEOUT이 나온다고 설명한다.

특히 Fluid Compute를 켠 프로젝트에서는 기본 duration과 확장 가능한 상한이 달라질 수 있다. 이미 Fluid Compute에서 duration과 memory를 같이 봐야 하는 이유 글을 읽었다면 이번 글은 실제 timeout이 났을 때 어떤 로그를 먼저 볼지에 가깝다.

세 번째 화면은 duration 설정 문서다. maxDuration을 늘리는 설정은 응답 시간을 더 주는 도구이지, 병목 자체를 없애는 도구가 아니라는 점을 여기서 같이 읽어야 한다.

Duration 설정 문서는 maxDuration이 함수에 더 긴 실행 시간을 준다고 설명한다.

그래서 timeout이 났다고 무조건 maxDuration만 늘리면 안 된다. 외부 API 대기나 region mismatch 때문에 느린 함수라면 상한을 늘려도 비용과 지연만 커질 수 있다.

네 번째 자료는 Runtime Logs 문서다. timeout을 코드만 보고 고치기보다 runtime logs에서 어떤 요청이 길어졌는지, 어느 함수와 어떤 deployment에서 반복되는지 먼저 보는 편이 빠르다.

Runtime Logs 문서는 로그를 검색하고 필터링해 timeout 요청을 추적하는 경로를 보여 준다.

Vercel은 build logs와 runtime logs가 갈리는 구조라서, timeout 원인을 찾을 때는 deployment build 성공 여부보다 runtime request 흐름을 먼저 봐야 한다. 이 단계가 빠지면 배포는 멀쩡한데 함수만 느린 상황을 놓친다.

다섯 번째 화면은 slow functions 디버깅 문서다. Vercel은 timeout 원인을 max duration 하나로 몰지 않고 memory, region, 외부 API latency 같은 조건과 같이 보라고 안내한다.

Slow functions 가이드는 max duration, memory, region, 외부 의존성을 함께 보라고 설명한다.

이 문서를 기준으로 보면 timeout은 설정 문제와 병목 문제를 같이 풀어야 한다. Cloud Run의 health check 비용 글처럼, 증상 하나를 봐도 실행 시간과 실제 런타임 경로를 같이 읽어야 원인이 좁혀진다.

마지막 자료는 timeout 점검 메모다. runtime logs를 볼 때 request path, deployment, upstream wait, maxDuration 설정을 한 번에 남겨 두면 '늘릴지 고칠지' 판단이 쉬워진다.

Vercel timeout 점검표는 maxDuration, Runtime Logs, upstream 대기를 같은 메모로 묶어 준다.

이 표를 기준으로 보면 timeout 대응은 두 갈래다. 현재 상한보다 약간 긴 정상 작업이라면 설정을 조정하고, 로그상 대기 시간이 길거나 무한 대기 패턴이 보이면 코드나 외부 의존성을 먼저 고친다.

5. 주의사항과 리스크

첫 번째 리스크는 timeout을 모두 maxDuration 부족으로 보는 것이다. 두 번째 리스크는 build logs만 보고 runtime request 경로를 확인하지 않는 것이다. 세 번째 리스크는 timeout을 피하려고 상한만 계속 늘려 비용과 응답 지연을 같이 키우는 것이다.

운영 전에는 route, deployment, maxDuration, upstream 대기 시간 정도는 메모로 남겨 두는 편이 좋다. 그래야 같은 timeout이 다시 났을 때 설정 문제와 병목 문제를 더 빨리 나눌 수 있다.

• timeout은 설정 문제와 병목 문제가 섞여 나타난다.
• Runtime Logs를 먼저 보고 route 단위로 좁힌다.
• 상한 확대는 정상 장기 작업일 때만 마지막에 검토한다.

6. 결론

Vercel FUNCTION_INVOCATION_TIMEOUT을 빠르게 줄이려면 maxDuration과 Runtime Logs를 같이 봐야 한다. 현재 상한이 충분한지 먼저 보고, 실제 로그에서 어느 route와 어떤 upstream 대기가 길었는지 확인한 뒤 설정 확대와 병목 수정을 분리하는 순서가 가장 안전하다.

• plan limit과 maxDuration을 먼저 확인한다.
• Runtime Logs로 route와 deployment를 좁힌다.
• 병목 수정과 상한 확대를 분리해서 결정한다.

7. 참고 링크

1. https://vercel.com/docs/errors/function_invocation_timeout
2. https://vercel.com/docs/functions/limitations
3. https://vercel.com/docs/functions/configuring-functions/duration
4. https://vercel.com/docs/logs/runtime
5. https://vercel.com/docs/functions/debug-slow-functions
6. https://vercel.com/docs/functions/usage-and-pricing