코디네이터 패턴을 플러터에 적용하며 생긴 _debugLocked 에러

📌 에러 메시지

Assertion failed: file:///Users/jayoengchoi/flutter/packages/flutter/lib/src/widgets/navigator.dart:5645:12
!_debugLocked is not true
See also: https://docs.flutter.dev/testing/errors

• Presentation Layer를 MVVM-C 패턴으로 로그인 유무에따라 코디네이터로 네비게이팅하는 코드가 있었다.
• Navigator.push() 호출 시 앱이 강제 종료(Crash) 되는 현상이 발생했다.

---

🔎 발생 원인 분석

1️⃣ _debugLocked란?

Flutter의 Navigator는 중복 네비게이션 호출을 방지하기 위해 _debugLocked 플래그를 사용한다.

• Navigator.push() 또는 Navigator.pop()이 호출되면 _debugLocked = true가 되어 애니메이션이 끝날 때까지 다른 네비게이션 호출을 막는다.
• _debugLocked == true 상태에서 추가로 push()를 호출하면 Assertion 에러가 발생한다.

📌 즉, 네비게이션 애니메이션이 끝나기 전에 새로운 push()를 호출하면 충돌이 발생한다.

 

2️⃣  navigatorKey.currentState == null

 

원래 앱의 시작점인 메인파일의 MaterialApp 에서 navigatorKey를 넣어주어야한다. 하지만 MVVM-C 패턴을 위해 화면전환 관련 코드는 코디네이터 객체에 캡슐화해 둔 상태였고 navigatorKey 가 늦게 호출됨에 따라 currentState == null 인 상황에서 첫 뷰전환이 발생하고 있었다.

 

3️⃣ navigatorKey.currentState == null과 _debugLocked의 관계

 

🚨 질문: navigatorKey가 null이면 왜 _debugLocked 에러가 발생할까?

 

navigatorKey.currentState == null인 상태에서 Navigator.push()를 호출하면 Flutter는 새로운 NavigatorState를 찾기 위해 build()를 트리거한다.

 

이 과정에서 다음과 같은 일이 발생한다:

1. Navigator.push()가 실행됨
   • 이때 navigatorKey.currentState == null이면 NavigatorState를 찾기 위해 build()가 다시 호출됨.
2. Flutter가 위젯을 리빌드하는 과정에서 _debugLocked가 활성화됨
   • Navigator는 애니메이션을 시작하기 위해 _debugLocked = true로 설정함.
   • 하지만 이 과정에서 다시 push()가 실행될 경우 _debugLocked가 이미 true 상태이므로 Assertion 에러가 발생.
3. 즉, navigatorKey.currentState == null 상태에서 push()를 호출하면 Navigator가 완전히 초기화되지 않은 상태에서 동작하게 되고, 이로 인해 _debugLocked가 예상치 못한 상태에서 유지됨.

📌 정리하면, navigatorKey.currentState == null 상태에서 네비게이션을 호출하면 Flutter가 네비게이터를 다시 초기화하는 과정에서 _debugLocked가 예상보다 오래 유지되며 충돌이 발생하는 것이다.

---

💡 해결 방법

WidgetsBinding.instance.addPostFrameCallback() 활용

WidgetsBinding.instance.addPostFrameCallback()  함수를 사용하게 되면 _debugLocked = false 가 되어야 다음 액션이 들어간다. 즉, 현재 UI 업데이트 및 애니메이션 및 셋팅이 완료된 이후에 실행되는 것이다. 따라서 이전 작업(navigator 빌드)가 완료되어 navigatorKey.currentState = null 이 아닌 상태에서 안전하게 Navigator.push()가 실행된다.