Next.js 15에서 params 경고 해결하기

문제 상황

Next.js 15 프로젝트에서 동적 API 라우트(/api/boards/[postId])를 구현하던 중 다음과 같은 오류가 발생했다.

Error: Route "/api/boards/[postId]" used `params.postId`. `params` should be awaited before using its properties.

 

아래의 API 라우트 핸들러에서 오류가 발생했습니다.

export async function GET(
  req: NextRequest,
  context: { params: { postId: string } }
) {
  const postId = context.params.postId; // 오류 발생

  const post = await prisma.post.findUnique({
    where: { postId: Number(postId) },
  });

  return NextResponse.json(post);
}

단순히 params.postId에 접근했을 뿐인데 에러를 발생시키고 작동하지 않았습니다.

 

그래서 공식문서와 stack overflow의 글들을 살펴보니

Next.js 15부터 params와 같은 일부 API 객체들이 내부적으로 비동기 Proxy 객체로 변경되었고.

비동기화된 객체에는 다음이 포함됩니다.

• params, searchParams
• cookies(), headers(), draftMode()

이 객체들은 더 이상 동기적으로 접근할 수 없으며, 반드시 await을 사용해 비동기적으로 접근해야 합니다.

즉, 다음처럼 직접 접근하는 방식은 오류를 유발합니다.

const postId = context.params.postId; // 오류 발생

 

그래서 처음에는 params객체가 비동기 객체로 변경되었다고 하길래

export async function GET(
  req: NextRequest,
  context: { params: { postId: string } }
) {
  const { postId } = await context.params;

  const post = await prisma.post.findUnique({
    where: { postId: Number(postId) },
  });

  return NextResponse.json(post);
}

이런식으로 단순히 await만 붙여봤는데 안됐습니다. 그래서 stack overflow를 뒤져보니 가져오는 params를 promise로 만들라는 글이 꽤 있었고 그렇게 수정해 봤습니다.

export async function GET(
  req: NextRequest,
  context: { params: Promise<{ postId: string }> }
) {
  const { postId } = await context.params;

  const post = await prisma.post.findUnique({
    where: { postId: Number(postId) },
  });

  return NextResponse.json(post);
}

 

이렇게 바꾸니 됩니다! 에러도 없고 정상작동 하네요

 

정리

• Next.js 15부터 params, searchParams, cookies(), headers() 등은 비동기 API가 되었다.
• context.params.postId처럼 동기적으로 직접 접근하면 오류가 발생한다.
• 반드시 await context.params로 접근하고 구조 분해 할당을 사용해야 한다.
• TypeScript에서는 params: Promise<{ ... }>로 명시하는 것이 바람직하다.

참고 자료

• Next.js 공식 문서: Dynamic APIs are Async
• stack overflow
• Next.js 15 업그레이드 가이드