← 개발일지

nextjs-vercel-build-error-date-object-fix

Next.jsVercel빌드에러트러블슈팅ReactYAMLfrontmatter

Next.js + Vercel 빌드 에러 해결기 — Date 객체와 Server Component 문제

Vercel에 Next.js 블로그를 배포하다가 빌드가 터졌다. 두 가지 에러를 만났고, 둘 다 원인을 알고 나면 허무할 정도로 간단한 문제였다. 같은 상황에 처한 분들을 위해 에러 메시지부터 해결까지 정리한다.

에러 1: Objects are not valid as a React child

에러 메시지

Error occurred prerendering page "/devlog/obsidian-google-calendar-setup-guide"

Error: Objects are not valid as a React child (found: [object Date]).
If you meant to render a collection of children, use an array instead.

왜 발생하는가

마크다운 파일의 YAML frontmatter에 날짜를 이렇게 적으면:

date: 2026-04-10

YAML 파서가 이걸 문자열 "2026-04-10"이 아니라 JavaScript Date 객체로 자동 변환한다. 이 Date 객체를 컴포넌트에서 그대로 렌더링하면 React가 거부한다. React는 객체를 자식 요소로 받지 않기 때문이다.

로컬 dev 모드에서는 멀쩡하다가 build 시점에 prerender 과정에서 터지는 경우가 많아서, 배포할 때 처음 마주치기 쉽다.

해결 방법

방법 1 — frontmatter에서 따옴표로 감싸기 (권장)

# ❌ Date 객체로 파싱됨
date: 2026-04-10

# ✅ 문자열로 유지됨
date: "2026-04-10"

가장 간단하고 근본적인 해결이다. YAML 파서가 애초에 문자열로 인식하기 때문에 컴포넌트 코드를 건드릴 필요가 없다.

방법 2 — 컴포넌트에서 변환

// ❌ Date 객체를 직접 렌더링
<p>{post.date}</p>

// ✅ 문자열로 변환 후 렌더링
<p>{new Date(post.date).toLocaleDateString("ko-KR")}</p>

// ✅ 또는 ISO 형식
<p>{new Date(post.date).toISOString().split("T")[0]}</p>

이미 작성된 마크다운 파일이 많아서 일일이 따옴표를 추가하기 어렵다면, 컴포넌트 쪽에서 한 번에 처리하는 게 효율적이다.

에러 2: Event handlers cannot be passed to Client Component props

에러 메시지

Error occurred prerendering page "/_not-found"

Error: Event handlers cannot be passed to Client Component props.
  {href: "/devlog", style: ..., onMouseEnter: function onMouseEnter, ...}
If you need interactivity, consider converting part of this to a Client Component.

왜 발생하는가

Next.js App Router에서 not-found.tsx는 기본적으로 Server Component다. 그런데 next/link의 Link 컴포넌트는 내부적으로 onMouseEnter, onMouseLeave 같은 이벤트 핸들러를 사용한다. Server Component에서는 이벤트 핸들러를 props로 전달할 수 없으므로 빌드가 실패한다.

해결 방법

해당 파일 최상단에 "use client" 지시문을 추가한다:

"use client";

import Link from "next/link";

export default function NotFound() {
  return (
    <div>
      <h1>404</h1>
      <p>페이지를 찾을 수 없습니다.</p>
      <Link href="/">홈으로 돌아가기</Link>
    </div>
  );
}

Link, useRouter, onClick 등 인터랙티브 요소가 포함된 페이지는 Client Component로 선언해야 한다.

번외: 수정했는데 Vercel에 반영이 안 될 때

빌드 에러를 고치고 로컬에서 확인까지 마쳤는데, Vercel 배포 사이트에 변경이 반영되지 않는 경우가 있다.

가장 흔한 원인은 Git push 누락이다. Vercel은 Git 저장소를 기반으로 빌드하기 때문에, 로컬에서 아무리 수정해도 push하지 않으면 아무 일도 일어나지 않는다.

# 현재 상태 확인
git status

# 커밋 이력 확인
git log --oneline -3

push가 정상인데도 반영이 안 된다면, Vercel 캐시를 의심해볼 수 있다:

  1. Vercel 대시보드 → Deployments
  2. 최근 배포 옆 ⋯ 클릭 → Redeploy
  3. "Use existing Build Cache" 체크 해제 후 재배포

정리

| 에러 | 원인 | 해결 | |---|---|---| | [object Date] is not valid as React child | YAML의 날짜가 Date 객체로 파싱됨 | frontmatter에서 date: "2026-04-10" 따옴표 추가 | | Event handlers cannot be passed to Server Component | Server Component에서 Link 등 인터랙티브 요소 사용 | "use client" 지시문 추가 | | 수정사항 미반영 | Git push 누락 또는 Vercel 캐시 | push 확인 또는 캐시 없이 Redeploy |

세 가지 모두 원인을 알면 1분 안에 고칠 수 있는 문제다. 하지만 에러 메시지만 보고는 원인을 바로 짐작하기 어려운 것들이라, 처음 겪으면 꽤 헤맬 수 있다.