Next.js 15 params should be awaited 에러 원인과 해결 가이드

Next.js 15 params should be awaited 에러 원인과 해결 가이드

3초 요약: 이렇게 고치세요
  • 원인: Next.js 15부터 params·searchParams가 Promise로 바뀌었는데, 예전처럼 params.id를 동기적으로 바로 읽어서 발생
  • 해결: 서버 컴포넌트·Route Handler·generateMetadata → const { id } = await params; / 클라이언트 컴포넌트 → const { id } = use(params);
  • 주의: 공식 codemod가 대부분 자동 변환해주지만, params를 조건부로 읽거나 다른 함수에 그대로 넘기는 패턴은 놓칠 수 있어 직접 확인 필요
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
}
↓ 왜 이런 에러가 나는지 원리 보기

Next.js 14 프로젝트를 15로 올리자마자 params.id를 쓰던 코드에서 "params should be awaited" 같은 경고나 타입 에러를 마주친 적 있으실 겁니다. 원인은 Next.js 15부터 동적 라우트의 params와 searchParams가 더 이상 일반 객체가 아니라 Promise로 바뀌었기 때문인데, 코드 몇 줄만 고치면 되는 문제지만 프로젝트 전체에 흩어져 있으면 손이 꽤 갑니다.

params가 갑자기 Promise가 된 이유

Next.js 14까지는 page.tsx가 받는 params·searchParams가 렌더링 시점에 이미 값이 채워진 평범한 객체였습니다. Next.js 15는 이 값들을 포함해 cookies(), headers(), draftMode()처럼 요청이 와야만 알 수 있는 값들을 전부 비동기 API로 통일했습니다. 정적으로 미리 렌더링할 수 있는 부분(레이아웃, 고정 텍스트 등)과 요청마다 달라지는 동적인 부분을 명확히 분리해서, 동적인 값이 실제로 필요한 지점까지는 페이지 셸을 먼저 그려두고 나머지를 스트리밍으로 채워 넣을 수 있게 하기 위한 구조 변경입니다.

그래서 예전처럼 params.id를 동기적으로 바로 읽으면, Next.js는 "이 값은 이제 Promise니까 await 없이 읽으면 안 된다"는 경고나 타입 에러를 띄웁니다.

최근 외주로 유지보수를 맡고 있는 프로젝트가 있는데, 버전을 계속 미뤄오다가 다른 패키지 업데이트 때문에 더는 미룰 수 없어서 Next.js 14에서 15로 한 번에 올리는 작업을 했습니다. 빌드는 문제없이 끝나길래 별일 아닌 줄 알고 넘어갔습니다. 그런데 다음 날 다른 작업자가 그 페이지에서 cookies()를 새로 쓰는 코드를 추가하다가 타입 에러를 만났고, 그제서야 콘솔에 계속 쌓이고 있던 params 관련 경고를 제대로 들여다봤습니다. Next.js가 당장은 이전 방식의 동기 접근도 어느 정도 호환되게 처리해주면서 경고만 띄우는 구간이 있어서 눈에 잘 안 띄었던 건데, 그땐 공식 codemod가 있는 줄도 모르고 프로젝트에 params.id를 쓰는 곳을 페이지·Route Handler 합쳐서 열 군데 넘게 직접 찾아 하나씩 await로 바꿨습니다. 나중에서야 자동 변환 도구가 있었다는 걸 알고 좀 허탈했습니다.

헷갈리기 쉬운 지점: codemod가 전부 잡아주지는 않는다

Next.js는 이 변경을 위한 공식 codemod(npx @next/codemod@latest next-async-request-api .)를 제공합니다. params.id처럼 곧바로 구조 분해하는 흔한 패턴은 대부분 자동으로 await 형태로 바꿔주지만, params를 그대로 다른 함수에 넘기거나 조건문 안에서만 접근하는 것처럼 조금만 패턴이 달라져도 놓치는 경우가 있습니다. codemod를 돌린 뒤에도 params·searchParams를 쓰는 곳을 한 번은 직접 검색해서 확인하는 게 안전합니다.

실전 해결 코드: 위치별 처리 방법

서버 컴포넌트 (page.tsx / layout.tsx)

// 이전 (Next.js 14 방식, 15부터 경고/에러)
export default function BlogPost({ params }: { params: { slug: string } }) {
  const { slug } = params;
  return <h1>{slug}</h1>;
}

// 이후 (Next.js 15)
export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>{slug}</h1>;
}

Route Handler

// app/api/posts/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  return Response.json({ id });
}

클라이언트 컴포넌트

클라이언트 컴포넌트는 async 함수로 만들 수 없기 때문에 await 대신 React의 use로 Promise를 언래핑합니다. 

'use client';
import { use } from 'react';

export default function BlogPostClient({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = use(params);
  return <h1>{slug}</h1>;
}

searchParams도 동일한 방식입니다. 서버 컴포넌트·Route Handler에서는 await searchParams, 클라이언트 컴포넌트에서는 use(searchParams)로 처리하면 됩니다. generateMetadata 함수도 같은 params를 받기 때문에 빠뜨리기 쉬운데, 여기도 동일하게 await로 풀어줘야 합니다.

위치별 처리 방법 정리

코드가 실행되는 위치에 따라 처리 방식이 다릅니다.

위치 처리 방법 비고
서버 컴포넌트 await params 컴포넌트 함수를 async로 선언해야 함
Route Handler await params GET/POST 등 핸들러 함수 자체가 이미 async
클라이언트 컴포넌트 use(params) 클라이언트 컴포넌트는 async로 선언할 수 없어 await 대신 use 사용
generateMetadata await params 서버 컴포넌트와 동일하지만 빠뜨리기 쉬움
공식 참고 레퍼런스

비동기 API 전환의 배경과 전체 마이그레이션 범위는 공식 문서에서 확인할 수 있습니다.

호마다의 웹개발 팁

Next.js의 비동기 렌더링과 스트리밍 구조를 좀 더 자세히 다룬 글은 [호마다의 IT 개발 입문 블로그] 에서 볼 수 있습니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

TypeScript: Unknown vs Any 타입 차이점과 안전한 타입 가드(Type Guard)

이미지
3초 요약: 이렇게 고치세요 원인: any 는 타입 검사 자체를 포기하는 선언이라, 잘못된 속성 접근이 컴파일 시점엔 통과했다가 런타임에 터짐 해결: 외부 API 응답처럼 타입을 확신할 수 없는 데이터는 unknown 으로 받고, data is T 형태의 타입 가드로 검증한 뒤에만 사용 주의: 타입 가드 내부에서 as Record<string, unknown> 같은 임시 캐스팅으로 속성을 하나씩 검사하는 절차를 생략하면 unknown 을 쓰는 의미가 없어짐 function isUserProfile(data: unknown): data is UserProfile { ... } ↓ 왜 any가 위험한지 원리 보기 실무에서 대규모 TypeScript 프로젝트를 마이그레이션하거나, 외부 API 또는 레거시 라이브러리를 통합하다 보면 필연적으로 "타입을 확신할 수 없는 데이터"를 다루게 됩니다. 이때 많은 개발자들이 급한 마음에 가장 손쉬운 탈출구인 any 를 사용하곤 합니다. 하지만 이는 TypeScript의 가장 큰 무기인 타입 안정성을 스스로 내려놓는 행위이자, 미래의 나에게 런타임 에러라는 시한폭탄을 던지는 것과 같습니다. any 가 왜 위험한지, TypeScript 3.0에서 도입된 unknown 이 이를 어떻게 막아주는지, 그리고 실무에서 바로 써먹을 수 있는 사용자 정의 타입 가드(User-Defined Type Guards) 작성 패턴을 정리합니다. any의 위험성과 unknown의 등장 프로덕션 환경에서 발생한 실제 에러 로그를 분석해 보면, 꽤 많은 비율이 TypeError: Cannot read properties of undefined 에서 시작합니다. 그리고 그 이면에는 높은 확률로 any 타입이 자리 잡고 있죠. any: 타입...
자세한 내용 보기

Next.js 하이드레이션 오류 원인과 해결법 완벽 정리

이미지
3초 요약: 이렇게 고치세요 원인: 서버가 렌더링한 초기 HTML과 브라우저가 처음 그린 HTML 구조가 서로 달라서 발생 — React는 둘이 같을 거라 믿고 결합을 시도하다가 실패함 해결: 잘못된 태그 중첩이면 마크업 수정 / window · localStorage 참조면 useEffect 로 이동 / 시간·랜덤값처럼 매번 달라지는 값이면 ssr: false 로 분리 주의: suppressHydrationWarning 은 경고를 숨길 뿐 원인을 고치는 게 아니라서, 불가피한 텍스트 불일치(타임스탬프 등)에만 제한적으로 써야 함 const [isMounted, setIsMounted] = useState(false); useEffect(() => setIsMounted(true), []); if (!isMounted) return null; // 서버와 첫 클라이언트 렌더는 항상 동일하게 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js를 쓰다 보면 콘솔에 "Hydration failed because the initial UI does not match..."라는 붉은 에러가 뜰 때가 있습니다. 빌드는 멀쩡히 끝났는데 화면이 그려진 직후에 갑자기 나는 에러라서 처음 보면 당황스럽습니다. 원인은 대부분 서버와 클라이언트가 그린 첫 화면이 미묘하게 다르기 때문이고, 패턴이 정해져 있어서 하나씩 짚어보면 금방 잡힙니다. 하이드레이션(Hydration), 정확히 어떤 과정인가 Next.js의 핵심 기능은 서버 사이드 렌더링(SSR)입니다. 서버는 먼저 사용자에게 정적인 HTML 뼈대를 빠르게 그려서 브라우저에 내려보내 줍니다. 그 후, 브라우저(클라이언트)가 이 정적인 HTML 위에 React의 자바스크립트 코드와 이벤트 리스너를 결합하여 ...
자세한 내용 보기

Next.js App Router에서 getServerSideProps 대체 및 데이터 페칭법

이미지
3초 요약: 이렇게 고치세요 원인: App Router는 서버 컴포넌트에서 직접 async/await를 쓸 수 있어 getServerSideProps / getStaticProps 가 아예 없어짐 해결: 빌드 시 캐싱(SSG) → 기본 fetch / 매 요청 최신화(SSR) → { cache: 'no-store' } / 주기 갱신(ISR) → { next: { revalidate: N } } 주의: getServerSideProps 안에 있던 인증 체크 로직은 이제 컴포넌트 함수 내부나 미들웨어로 옮겨야 함 const res = await fetch(url, { cache: 'no-store' }); // SSR과 동일하게 매번 재요청 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js 13 이상에서 App Router가 표준이 되면서, Pages Router에서 쓰던 getServerSideProps 와 getStaticProps 가 더 이상 동작하지 않습니다. 두 함수가 사라진 설계적 이유와, 이를 대체하는 데이터 패칭 방식을 정리했습니다. 왜 getServerSideProps와 getStaticProps가 사라졌을까 과거 Next.js는 페이지 컴포넌트 내부에서만 특정 정적 함수( getServerSideProps 등)를 실행하여 데이터를 미리 받아온 뒤, 이를 컴포넌트의 props 로 넘겨주는 복잡한 직렬화 구조를 가졌습니다. 이로 인해 컴포넌트 간 깊이가 깊어지면 'Props Drilling(프로퍼티 대물림)'이 심해져 코드 관리가 몹시 까다로웠습니다. App Router 환경에서는 서버 컴포넌트(Server Component)가 표준이 됨에 따라 컴포넌트 내에서 직접 비동기 함수(async/await)를 작성할 수 있게 되었습...
자세한 내용 보기