02892025년 9월 7일

Flutter + Rive 연동 시 발생한 에러 해결기

Flutter에서 Rive 애니메이션을 사용하면서 자산 로드/아트보드 로드 에러를 겪을 수 있습니다. 이번 포스팅에서는 제가 겪었던 문제와 해결 방법을 공유합니다.

1. 발생한 에러들

처음에는 Rive 애니메이션 파일(.riv)을 불러오려고 했을 때 다음과 같은 에러가 발생했습니다.

(1) Unable to load asset

code

Unhandled Exception: Unable to load asset: "assets/animations/bear_avatar_remix.riv".
The asset does not exist or has empty data.

→ Flutter가 아예 파일을 못 찾는 상황입니다.

(2) Unable to load artboard

SQL

Unhandled Exception: FormatException: Unable to load artboard

→ 이번엔 파일은 불러왔지만, 내부 Artboard 이름을 못 찾는 상황입니다.

2. 원인 분석

문제의 원인은 크게 두 가지였습니다.

✅ (1) pubspec.yaml 설정

pubspec.yaml에서 asset 경로를 등록할 때 폴더 단위로 등록해야 합니다.

code

flutter:
  assets:
    - assets/animations/

⚠️ assets/animations (슬래시 누락) → 제대로 인식 안 됨
✅ assets/animations/ (슬래시 포함) → 정상 인식

✅ (2) Artboard 이름 불일치

Rive 파일 내부에는 Artboard라는 단위가 있습니다.
제가 사용한 bear_avatar_remix.riv 파일의 아트보드 이름은 "Artboard"였는데,
코드에서는 "Bear Avatar Remix"라고 잘못 지정해서 발생한 문제였습니다.

3. 해결 방법

(1) pubspec.yaml 수정

YAML

flutter:
  uses-material-design: true
  assets:
    - assets/animations/

수정 후 꼭 실행:

code

flutter clean
flutter pub get

(2) 코드 수정

code

RiveAnimation.asset(
  "assets/animations/bear_avatar_remix.riv",
  fit: BoxFit.cover,
  artboard: "Artboard",                 // ? 실제 Artboard 이름
  stateMachines: const ["State Machine 1"], // ? 실제 State Machine 이름
  onInit: _onInit,
),

4. 최종 결과

Unable to load asset → pubspec.yaml 경로 문제
Unable to load artboard → Artboard 이름 불일치 문제

두 가지를 수정하니 정상적으로 곰돌이 애니메이션이 Flutter에서 실행되었습니다 ?

5. 배운 점

pubspec.yaml 경로 등록: 폴더 단위로 /까지 붙여줘야 한다.
Rive 내부 Artboard/State Machine 이름: 편집기에서 확인한 이름과 완전히 동일하게 써야 한다. (띄어쓰기, 대소문자 모두 구분됨)
에러 메시지를 단계별로 해석하면 원인에 빠르게 접근할 수 있다.

? 이번 경험을 통해, Flutter + Rive 연동에서 자주 나오는 함정을 정리할 수 있었습니다. 앞으로 비슷한 문제를 겪는 분들께 도움이 되길 바랍니다 ?

최근 글