React에서 Error: Element type is invalid 에러 완벽 해결 가이드

도입

React 개발 중 “Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined”라는 에러 메시지를 만난 적이 있나요? Error: Element type is invalid 에러는 React 개발자라면 누구나 한 번쯤 마주치는 흔한 에러입니다. 이 에러는 주로 컴포넌트를 잘못 import하거나 export할 때 발생하며, 초보 개발자뿐만 아니라 숙련된 개발자도 종종 겪는 문제입니다. 특히 프로젝트 규모가 커질수록 컴포넌트 간의 의존성이 복잡해지면서 이런 에러가 발생할 가능성이 높아집니다. 이 글에서는 에러의 정확한 원인과 효과적인 해결 방법, 그리고 예방법까지 상세히 알아보겠습니다.

에러 상세 분석

이 에러 메시지는 React가 렌더링하려는 요소의 타입이 유효하지 않을 때 발생합니다. React는 컴포넌트를 렌더링할 때 문자열(HTML 태그), 함수형 컴포넌트, 또는 클래스형 컴포넌트를 기대합니다. 하지만 undefined, null, 또는 잘못된 값이 전달되면 이 에러가 발생합니다.

에러 메시지의 구조를 살펴보면:

• expected a string: HTML 기본 태그(div, span 등)를 의미
• class/function: React 컴포넌트를 의미
• but got: undefined: 실제로 받은 값이 undefined임을 나타냄

이 에러는 주로 개발 환경에서 즉시 발견되며, 브라우저 콘솔에 빨간색으로 표시됩니다. 에러가 발생하면 애플리케이션이 정상적으로 렌더링되지 않고, 화면에 에러 오버레이가 나타나거나 빈 화면만 보이게 됩니다. 스택 트레이스를 확인하면 정확히 어느 컴포넌트에서 문제가 발생했는지 추적할 수 있습니다.

발생 원인 5가지

1. Named Export와 Default Export 혼동

가장 흔한 원인입니다. 컴포넌트를 export하는 방식과 import하는 방식이 일치하지 않을 때 발생합니다. Named export로 내보낸 컴포넌트를 default import로 가져오거나, 그 반대의 경우에 이 에러가 나타납니다.

2. 존재하지 않는 컴포넌트 Import

파일 경로가 잘못되었거나, 컴포넌트 이름이 변경되었는데 import 구문을 업데이트하지 않은 경우입니다. 또는 컴포넌트가 실제로 export되지 않았는데 import하려고 할 때도 발생합니다.

3. 순환 참조(Circular Dependency)

두 개 이상의 파일이 서로를 import하는 순환 참조 상황에서 발생할 수 있습니다. 이 경우 모듈 로딩 순서에 따라 일부 컴포넌트가 undefined로 평가될 수 있습니다.

4. 컴포넌트를 JSX로 잘못 전달

컴포넌트 자체를 전달해야 하는데 JSX 요소를 전달하거나, 컴포넌트를 호출한 결과를 전달하는 경우입니다. 예를 들어 <Component />를 전달해야 하는데 Component()를 전달하는 실수입니다.

5. 라이브러리 버전 충돌

React 라이브러리나 관련 패키지의 버전이 호환되지 않거나, node_modules가 손상된 경우에도 이 에러가 발생할 수 있습니다. 특히 여러 버전의 React가 동시에 설치된 경우 문제가 됩니다.

해결방법 7가지

방법 1: Export/Import 방식 확인 및 수정

가장 먼저 확인해야 할 사항입니다. Export와 import 방식을 일치시키세요.

// ❌ 잘못된 예 - Button.jsx
export const Button = () => {
  return <button>Click</button>;
};

// App.jsx에서 잘못된 import
import Button from './Button'; // undefined 반환!

// ✅ 올바른 해결법 1: Named import 사용
import { Button } from './Button';

// ✅ 올바른 해결법 2: Default export로 변경
// Button.jsx
const Button = () => {
  return <button>Click</button>;
};
export default Button;

// App.jsx
import Button from './Button';

방법 2: 파일 경로 확인

Import 경로가 정확한지 확인하세요. 상대 경로와 절대 경로를 혼동하지 않도록 주의합니다.

// ❌ 잘못된 경로
import Header from './components/Header'; // 파일이 실제로는 다른 위치에 있음

// ✅ 올바른 경로
import Header from '../components/Header';
// 또는 절대 경로 사용 (jsconfig.json 설정 필요)
import Header from '@/components/Header';

방법 3: 컴포넌트가 실제로 Export되는지 확인

컴포넌트 파일에서 export 구문이 있는지 확인하세요.

// ❌ Export 누락
const Card = ({ title }) => {
  return <div>{title}</div>;
};
// export 구문 없음!

// ✅ Export 추가
const Card = ({ title }) => {
  return <div>{title}</div>;
};
export default Card;

방법 4: Index.js를 사용한 Re-export 확인

여러 컴포넌트를 index.js에서 re-export하는 경우 구문이 올바른지 확인합니다.

// ❌ 잘못된 re-export - components/index.js
export { default as Button } from './Button'; // Button이 named export인 경우 오류

// ✅ 올바른 방법 1: Default export인 경우
export { default as Button } from './Button';

// ✅ 올바른 방법 2: Named export인 경우
export { Button } from './Button';

// ✅ 올바른 방법 3: 모든 것을 re-export
export * from './Button';

방법 5: 동적 Import 확인

React.lazy를 사용한 동적 import의 경우 default export를 사용해야 합니다.

// ❌ Named export를 lazy로 import
const Dashboard = React.lazy(() => 
  import('./Dashboard').then(module => ({ default: module.Dashboard }))
); // 복잡함

// ✅ Dashboard를 default export로 변경
// Dashboard.jsx
const Dashboard = () => <div>Dashboard</div>;
export default Dashboard;

// App.jsx
const Dashboard = React.lazy(() => import('./Dashboard'));

방법 6: 콘솔 로그로 디버깅

Error: Element type is invalid 에러를 추적하기 위해 import한 컴포넌트를 콘솔에 출력해봅니다.

import Header from './Header';
console.log('Header:', Header); // undefined가 출력되면 import 문제

// 또는 import 직후 확인
import * as HeaderModule from './Header';
console.log('HeaderModule:', HeaderModule); // 어떤 것이 export되는지 확인

방법 7: node_modules 재설치

패키지 의존성 문제인 경우 node_modules를 삭제하고 재설치합니다.

// 터미널에서 실행
rm -rf node_modules package-lock.json
npm install

// 또는 yarn 사용 시
rm -rf node_modules yarn.lock
yarn install

// 캐시도 함께 정리
npm cache clean --force
npm install

예방법과 베스트 프랙티스

1. 일관된 Export 방식 사용

프로젝트 전체에서 하나의 export 방식을 통일하여 사용하는 것이 좋습니다. 일반적으로 컴포넌트는 default export를, 유틸리티 함수는 named export를 사용하는 것이 권장됩니다.

2. ESLint 규칙 설정

ESLint의 import/export 관련 규칙을 활성화하여 잘못된 import를 사전에 감지하세요. eslint-plugin-import 플러그인을 사용하면 유용합니다.

3. TypeScript 도입 고려

TypeScript를 사용하면 컴파일 시점에 import/export 오류를 발견할 수 있어 런타임 에러를 크게 줄일 수 있습니다.

4. 절대 경로 설정

jsconfig.json 또는 tsconfig.json에서 절대 경로를 설정하면 상대 경로로 인한 실수를 방지할 수 있습니다.

// jsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@/components/*": ["components/*"],
      "@/utils/*": ["utils/*"]
    }
  }
}

마무리

React의 Error: Element type is invalid 에러는 대부분 import/export 불일치로 인해 발생하는 문제입니다. 이 글에서 소개한 7가지 해결 방법을 순서대로 적용해보면 대부분의 경우 문제를 해결할 수 있습니다. 특히 export 방식과 import 방식을 일치시키는 것이 가장 중요합니다. 앞으로는 일관된 코딩 컨벤션을 유지하고, TypeScript나 ESLint 같은 도구를 활용하여 이런 에러를 사전에 예방하는 것을 권장합니다. 개발 과정에서 이 에러를 만나더라도 당황하지 말고 차근차근 원인을 찾아 해결해나가시기 바랍니다.