live2d-web 문서

문제 해결

모델 로드, Cubism Core, 렌더링, 트래킹 문제의 원인을 찾습니다.

오류 코드부터 확인

Live2DError에는 변하지 않는 오류 코드와 문제가 난 자산의 URL, 종류, HTTP 상태가 있습니다. 이 값과 브라우저, 모델을 내보낸 버전을 이슈에 적되 라이선스 자산은 첨부하지 마세요.

원인: SSR·Node 환경이나 DOM을 사용할 수 없는 Worker에서 브라우저 API를 호출했습니다. 확인: 호출 스택에서 첫 createLive2D() 또는 DOM 의존 호출을 찾습니다. 수정: 컴포넌트가 마운트된 뒤 호출하고, Next.js에서는 Client Component에서 /react를 불러옵니다. 재시도: 브라우저에서 실행하도록 옮기기 전에는 불가능합니다.

core-missing

원인: coreUrl의 Cubism Core를 불러오지 못했고 호환되는 전역 Core도 없습니다. 확인: 스크립트 요청, CSP, CORS, Core 5.3 URL을 확인합니다. 수정: 공식 Core를 직접 호스팅하고 접근 가능한 URL을 전달합니다. 재시도: 경로나 정책을 고친 뒤 가능합니다.

webgl-unsupported

원인: 브라우저가 WebGL2 컨텍스트를 만들지 못했습니다. 확인: WebGL2 지원 여부, 하드웨어 가속, 현재 사용 중인 컨텍스트 수를 확인합니다. 수정: 지원 브라우저나 GPU를 사용하거나 다른 Canvas를 정리합니다. 재시도: 환경이 바뀐 뒤에만 유효합니다.

invalid-props

원인: API 인자나 옵션이 문서에 정한 형식 또는 범위를 벗어났습니다. 확인: 오류 메시지에 나온 필드를 확인합니다. 수정: 호출 값을 고칩니다. 재시도: 같은 값으로는 해결되지 않습니다.

invalid-tree

원인: React 컴포넌트가 필요한 Provider 밖에 있거나, 하나의 Canvas에 모델이 둘 이상 연결되어 있습니다. 확인: Live2DCanvas와 Live2DModel 주변의 컴포넌트 구조를 확인합니다. 수정: Canvas 하나에 모델 하나만 두고 Hook을 해당 Provider 안에서 사용합니다. 재시도: 구조를 바꾸기 전에는 불가능합니다.

lipsync-error

원인: 선택형 립싱크를 준비하거나 처리하는 중에 실패했습니다. 확인: 보안 연결, 마이크 권한, AudioContext 상태, wLipSync 프로필을 확인합니다. 수정: 사용자가 화면을 조작한 시점에 오디오를 재개하거나 볼륨 드라이버를 사용합니다. 재시도: 오디오 설정을 고친 뒤 가능하며 모델 렌더링은 계속할 수 있습니다.

tracking-error

원인: MediaPipe 초기화, 추론, Worker 통신 또는 정리 과정에서 실패했습니다. 확인: 선택형 의존성, WASM·task 경로, CORS, CSP의 worker-src, 제한 시간과 브라우저 지원 여부를 확인합니다. 수정: 자산이나 Worker 설정을 고치고 Worker를 지원하지 않으면 Main thread를 선택합니다. 재시도: 원인을 고친 뒤 트래커를 새로 만듭니다.

model-load-failed

원인: model3 또는 참조 자산에 HTTP 오류, CORS 차단, 파일 누락, 구문 분석 실패가 있습니다. 확인: details.url, assetType, httpStatus와 브라우저의 Network 패널을 확인합니다. 404는 주로 잘못된 경로, 상태 코드가 없는 요청 실패는 CORS나 네트워크 문제, 구문 분석 오류는 손상됐거나 호환되지 않는 모델일 가능성이 큽니다. 수정: 파일명의 대소문자, 참조 경로, MIME 유형, CORS 헤더를 바로잡거나 모델을 다시 내보냅니다. 재시도: 일시적인 네트워크 오류이거나 자산을 수정한 뒤 가능합니다.

render-error

원인: 준비가 끝난 뒤 렌더링이 중단됐습니다. 흔한 원인은 WebGL 컨텍스트 손실입니다. 확인: 콘솔에 처음 나타난 오류와 GPU 컨텍스트 수를 확인합니다. 수정: GPU 부담을 줄이고 Canvas 오류 화면에서 다시 시도합니다. 재시도: 가능하며 Stage 옵션을 유지한 채 다시 만듭니다.

adapter-error

원인: Backend가 지원하지 않는 기능을 요청했거나 다른 Backend의 핸들을 받았습니다. 확인: Backend 이름과 옵션 지원표를 확인합니다. 수정: 기본 Backend를 사용하거나 지원하지 않는 옵션을 제거하고 사용자 정의 어댑터를 갱신합니다. 재시도: 설정을 바꾸기 전에는 해결되지 않습니다.

가장 작은 장면으로 재현하기

MediaPipe, 마이크, custom parameter driver를 끄고 기본 Backend에서 모델 하나만 불러오세요. 뒤이은 console 메시지보다 첫 Live2DError를 기록합니다. 브라우저, 라이브러리·Core·export 버전, code, assetType, HTTP 상태, 실패 URL을 남기세요.

const character = await createLive2D({
  container: document.querySelector('#stage')!,
  coreUrl: '/live2dcubismcore.min.js',
  src: '/models/model.model3.json',
})
 
console.log(character.getModelInfo())
await character.playMotion('Idle', 0)

자원을 남기지 않고 복구하기

재시도 전에 driver를 해제하고 tracker와 runtime을 dispose하며 media track을 중지한 뒤 기존 Canvas가 제거됐는지 확인합니다. 경로·정책·지원 환경을 수정한 뒤 새 인스턴스를 만드세요. 같은 오류에서 retry를 반복하면 중복 요청만 늘어납니다.