Objects are not valid as a React child 해결: 객체는 필드로, 배열은 map으로

화면을 열자 Objects are not valid as a React child가 뜨고 object with keys {id, name} 같은 문구가 보인다면, React 설치가 망가진 것이 아니다. JSX 자식 자리에 화면 값이 아니라 JavaScript 객체 전체가 들어간 상태다.

먼저 오류에 표시된 키를 코드에서 검색한다. 문제 JSX를 찾으면 {user}를 {user.name}처럼 필요한 필드로 바꾼다. 값이 객체 배열이라면 각 항목을 map으로 React 요소로 변환한다. 패키지를 다시 설치하거나 캐시를 지우기 전에 렌더링한 값의 자료형부터 확인한다.

Tap to zoom

객체 전체 대신 화면에 필요한 값을 꺼낸다

API에서 사용자 정보를 받았다고 가정한다. 아래 코드는 user 객체 자체를 제목 안에 넣는다. React는 그 객체를 어떤 화면 문자열로 바꿔야 할지 알 수 없어 렌더링을 중단한다.

const user = { id: 7, name: '민지', role: '관리자' };

return <h2>{user}</h2>;

화면 목적에 맞는 필드를 골라 쓰면 된다.

return (
  <h2>
    {user.name} · {user.role}
  </h2>
);

React 공식 JSX 문서도 객체 person 전체를 넣은 실패 예제와 {person.name}을 사용한 정상 예제를 나란히 보여 준다. 중괄호가 문제인 것이 아니라 중괄호 안에 들어온 값의 종류가 문제다. 객체는 style={person.theme}처럼 객체를 받는 prop에는 맞지만, <h1>{person}</h1>처럼 화면 자식으로 바로 출력할 수는 없다.

오류 메시지의 키로 문제 JSX를 찾는다

AI가 만든 파일이 많을수록 처음부터 모든 JSX를 읽는 방식은 느리다. 오류 메시지에 object with keys {id, name, role}가 보이면 role처럼 비교적 고유한 키를 프로젝트에서 검색한다.

rg "role" app src components

검색 결과에서 JSX 중괄호 안에 객체가 직접 들어간 곳을 찾는다. 변수 이름이 user가 아닐 수도 있으므로 이름보다 실제 값의 모양을 본다.

// 확인할 형태
<p>{profile}</p>
<Badge>{result.data}</Badge>
<option>{item}</option>

Tap to zoom

브라우저에 일부 데이터만 잠시 확인하려면 개발 중에 JSON.stringify(profile, null, 2)를 <pre> 안에 넣을 수 있다. 다만 이는 문제 위치를 찾는 임시 관찰 도구다. 실제 사용자 화면이라면 이름, 상태, 날짜처럼 목적에 필요한 필드를 선택해 별도 요소로 배치해야 한다.

콘솔과 화면을 함께 좁히는 방법은 React 개발 서버는 켜졌는데 화면이 하얄 때 Console로 원인을 찾는 순서와 연결된다. 화면이 비어도 첫 오류 한 줄부터 고치면 뒤따른 오류가 함께 사라지는 경우가 많다.

객체·배열·날짜에 따라 수정법이 달라진다

문제 위치를 찾은 뒤에는 값의 실제 모양을 확인한다. console.log(value)만 보지 말고 배열 여부와 필요한 필드를 함께 기록하면 수정 방향이 빨리 갈린다.

console.log({
  value,
  isArray: Array.isArray(value),
  type: typeof value,
});

단일 객체는 필요한 필드를 고른다

프로필 한 건이라면 profile.name, profile.status처럼 독자가 볼 값을 고른다. 데이터가 아직 없을 수 있다면 React의 조건부 렌더링 방식에 맞춰 로딩과 빈 상태를 분리한다.

if (!profile) return <p>사용자 정보를 불러오는 중이다.</p>;

return <p>{profile.name}</p>;

객체 배열은 map으로 요소를 만든다

React 공식 목록 렌더링 문서는 데이터 배열을 map으로 JSX 배열로 바꾸는 방식을 안내한다. 객체 배열 자체를 넣지 말고 각 객체에서 표시할 값을 꺼낸다.

return (
  <ul>
    {users.map((user) => (
      <li key={user.id}>{user.name}</li>
    ))}
  </ul>
);

key는 렌더링 도중 만든 난수보다 데이터에 이미 있는 안정적인 ID를 쓴다. 객체 오류를 고친 뒤 key 경고가 남는다면 React key warning에서 map 안의 id부터 확인하는 방법을 이어서 점검하면 된다.

날짜와 복합 값은 표시 형식을 정한다

Date 인스턴스나 중첩 객체도 사용자에게 어떤 표현이 필요한지 먼저 정한다. 날짜라면 Intl.DateTimeFormat으로 문자열을 만들고, 주소 객체라면 city와 district를 조합한다. 무조건 문자열 변환을 붙이는 대신 화면의 의미를 코드에 남긴다.

개발 서버와 빌드에서 다시 확인한다

수정 뒤에는 화면이 한 번 뜨는 것만 보지 않는다. 다음 네 항목을 순서대로 확인한다.

Tap to zoom

1. 오류가 난 경로를 새로고침해 같은 데이터에서 화면이 뜨는지 본다.
2. 개발자 도구 Console에서 object-child 오류가 사라졌는지 확인한다.
3. 배열을 map으로 바꿨다면 key 경고가 새로 생기지 않았는지 본다.
4. 프로젝트의 빌드 명령을 실행해 프로덕션 렌더링도 통과하는지 확인한다.

npm run build

프로덕션에서 전체 문구 대신 React의 축약 오류 번호가 보이면 공식 오류 31 디코더에서 원문을 확인할 수 있다. 원문도 일반 객체를 child로 렌더링할 수 없다는 내용이다. 개발 환경은 더 자세한 정보를 주므로 가능하면 같은 데이터로 로컬에서 먼저 재현한다.

여기까지 통과하면 객체를 숨긴 것이 아니라 화면 목적에 맞는 값으로 바꾸고, 배열 항목의 정체성까지 확인한 상태다. 다음에 같은 오류가 나오면 오류 키 검색 → JSX 값 확인 → 단일 객체와 배열 구분 → 개발·빌드 재검증 순서로 반복한다.

참고 출처

• JavaScript in JSX with Curly Braces: React
• Rendering Lists: React
• Minified React error #31: React
• Conditional Rendering: React

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.