[Next.js/Cloudflare] 배포 후 구글 로그인 500 에러, async_hooks 완벽 해결법

로컬에선 잘 되는데 서버에선 500 에러가 난다고요?

Next.js와 Supabase를 이용해 구글 소셜 로그인(OAuth)을 구현하고, 자랑스럽게 Cloudflare Pages에 배포했습니다. 로컬(localhost:3000)에서는 구글 로그인 창도 잘 뜨고 세션도 완벽하게 받아왔습니다.

하지만 배포된 프로덕션 URL에서 로그인을 시도하는 순간, 자비 없는 500 Internal Server Error를 마주하게 됩니다. 구글 클라우드 콘솔의 리디렉션 URI를 의심해 보고, Supabase의 API 키가 잘못 들어갔는지 수십 번 확인했지만 원인은 거기가 아니었습니다.

Cloudflare 대시보드에서 실시간 로그(Real-time Logs)를 뜯어보니 아래와 같은 에러가 찍혀 있었습니다.

Error: No such module "__next-on-pages-dist__/functions/auth/async_hooks".
imported from "__next-on-pages-dist__/functions/auth/callback.func.js"

에러의 진짜 원인: Edge 런타임과 Node.js 호환성

이 문제는 Next.js(특히 15 버전 이상)가 쿠키와 세션을 다룰 때 내부적으로 Node.js의 async_hooks 모듈을 사용하기 때문에 발생합니다.

Cloudflare Pages는 가볍고 빠른 Edge(엣지) 런타임을 사용하는데, 여기에는 기본적으로 Node.js 전용 모듈들이 비활성화되어 있습니다. 따라서 서버가 async_hooks를 찾지 못해 장렬하게 터져버린 것입니다.

완벽한 해결 방법 (3단계)

이 문제는 코드를 뜯어고칠 필요 없이, Cloudflare의 **Node.js 호환성 모드(nodejs_compat)**를 켜고 호환성 날짜를 최신화해주면 마법처럼 해결됩니다.

하지만 대시보드에서 마우스로 클릭해서 설정하면 배포할 때마다 설정이 과거로 회귀하는 버그(?)를 겪을 수 있습니다. 가장 확실한 베스트 프랙티스인 wrangler.toml을 이용한 해결법을 소개합니다.

1. 프로젝트 루트에 `wrangler.toml` 파일 생성 또는 수정

프로젝트 최상단 폴더에 wrangler.toml 파일을 열고(없다면 새로 만듭니다), 아래와 같이 코드를 작성합니다.

name = "내프로젝트이름"
compatibility_date = "2024-09-23" # 이 날짜가 핵심입니다!
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = ".vercel/output/static"

compatibility_date: 반드시 2024-09-23 이후의 날짜(또는 오늘 날짜)로 설정해야 합니다. Cloudflare가 새롭게 업데이트한 강력한 nodejs_compat v2 시스템을 태우기 위한 필수 조건입니다.
compatibility_flags: Edge 환경에서 Node.js 모듈(async_hooks 등)을 사용할 수 있게 허락해 줍니다.

2. 로그인 콜백 라우트에 Edge 런타임 명시 (옵션)

Supabase 로그인 후 돌아오는 콜백 처리 파일(예: app/auth/callback/route.ts) 최상단에 런타임이 명시되어 있는지 확인합니다.

// app/auth/callback/route.ts
export const runtime = 'edge'

// ... (나머지 로직)

3. Git Commit & Push (새로운 빌드 유도)

주의할 점: Cloudflare 대시보드에서 '배포 재시도(Retry deployment)'를 누르면 안 됩니다! 재시도 버튼은 과거의 낡은 세팅을 다시 끌고 오기 때문입니다.

반드시 코드를 수정하거나 띄어쓰기라도 하나 추가한 뒤, 터미널에서 git push를 날려 새로운 빌드를 유도해야 합니다.

git add .
git commit -m "fix: async_hooks 500 error resolve"
git push origin main

마무리

배포가 완료되고 다시 프로덕션 환경에서 구글 로그인을 시도해 보세요. 지긋지긋했던 500 에러가 사라지고 무사히 메인 화면으로 리디렉션되는 것을 볼 수 있습니다.

단순히 대시보드에서 클릭 몇 번으로 해결할 수도 있지만, wrangler.toml 파일로 인프라 설정을 코드화(IaC)해두면 추후 Vercel이나 다른 환경으로 마이그레이션할 때나 팀원들과 협업할 때 훨씬 쾌적한 개발 경험을 유지할 수 있습니다.

저와 같은 에러로 고통받고 계셨던 분들께 도움이 되었길 바랍니다!