[에러 해결] Flet 앱 실행 안 됨: ‘Exception in thread’ 원인과 해결 방법

Flet으로 멋진 크로스 플랫폼 애플리케이션을 개발하고 있는데, 분명히 코드를 작성했는데도 앱이 실행되지 않고 알 수 없는 Exception in thread 메시지만 보인다면 정말 답답할 것입니다. 특히 처음 Flet을 접하는 개발자라면 더욱 그렇겠죠. 이 문서에서는 Flet 앱이 정상적으로 표시되지 않고 스레드 예외가 발생하는 흔한 원인을 분석하고, 명확한 해결책을 제시합니다.

1. 에러 발생 상황

개발 환경은 VS Code이며, Flet 앱을 실행하려고 시도했을 때 터미널에는 아래와 같은 메시지가 나타납니다. Flet 초기 설정 메시지(“Preparing Flet v1.0.1 for the first use.”) 이후에 Exception in thread Thread-4와 같은 일반적인 스레드 예외 메시지만 표시될 뿐, Flet 창은 나타나지 않습니다.

문제의 소스 코드:

import flet as ft

def main(page: ft.Page):
  page.title = 'Counter'
  body = ft.Container( bgcolor=ft.Colors.RED,
                       expand=True,
                       height=page.height,
                       width=page.width,
                       content=ft.Column( ft.Text( value='Counter App',
                                                   size=50, style=ft.TextStyle( color=ft.Colors.WHITE, )
                                                 ), 
                                        )
                     )
  page.add(body)
  if name == "main": # <-- 이 부분이 문제입니다!
    ft.run(main)

2. 명확한 발생 원인

이 문제의 핵심 원인은 Python 스크립트 실행의 기본 규칙을 따르지 않은 코드 줄에 있습니다. 바로 if name == "main": 이라는 조건문입니다.

Python에서는 스크립트가 직접 실행될 때 __name__ 이라는 특수 변수에 "__main__" 문자열이 할당됩니다. 이는 다른 모듈에서 import될 때와 구분하기 위한 중요한 메커니즘입니다. Flet 앱을 실행하는 ft.run(main) 함수는 일반적으로 스크립트가 직접 실행될 때만 호출되어야 합니다.

하지만 제공된 코드에서는 __name__ 대신 name이라는 변수를 사용하고 있습니다. Python에는 name이라는 전역 변수가 기본적으로 존재하지 않으므로, 이 조건문은 항상 거짓(False)이 됩니다. 결과적으로 ft.run(main) 호출이 건너뛰어져 Flet 애플리케이션이 시작되지 않고, 이로 인해 내부적으로 Flet 프로세스가 제대로 초기화되지 못하여 일반적인 스레드 예외가 발생하게 됩니다.

3. 해결 방법 및 코드 예시

해결 방법은 매우 간단합니다. if name == "main": 부분을 올바른 Python 구문인 if __name__ == "__main__":으로 수정하는 것입니다.

수정된 코드는 다음과 같습니다:

import flet as ft

def main(page: ft.Page):
  page.title = 'Counter'
  body = ft.Container( bgcolor=ft.Colors.RED,
                       expand=True,
                       height=page.height,
                       width=page.width,
                       content=ft.Column( ft.Text( value='Counter App',
                                                   size=50, style=ft.TextStyle( color=ft.Colors.WHITE, )
                                                 ), 
                                        )
                     )
  page.add(body)

if __name__ == "__main__": # <-- 수정된 부분
  ft.run(main)

이 코드로 수정하면 스크립트가 직접 실행될 때 if __name__ == "__main__": 조건이 참이 되어 ft.run(main)이 정상적으로 호출됩니다. Flet 앱은 올바르게 초기화되고 지정된 'Counter' 창이 화면에 표시될 것입니다.

4. 향후 예방을 위한 팁

이와 같은 오류를 방지하고 더 나은 개발 경험을 위해 몇 가지 팁을 드립니다:

• Python 특수 변수 이해

  __name__과 같은 이중 밑줄(dunder)로 시작하고 끝나는 특수 변수나 메서드는 Python에서 특별한 의미를 가집니다. 이들의 정확한 용법을 이해하는 것이 중요합니다. if __name__ == "__main__": 패턴은 Python 스크립트에서 진입점을 정의하는 가장 기본적인 방법 중 하나입니다.

• IDE의 린팅(Linting) 기능 활용

  VS Code와 같은 현대적인 IDE는 Python 확장 기능과 함께 강력한 린팅 기능을 제공합니다. name과 같이 정의되지 않은 변수를 사용하면 대부분의 린터가 이를 경고로 표시해 줄 것입니다. 이러한 경고 메시지를 주의 깊게 확인하고 해결하는 습관을 들이세요.

• 공식 문서 참고 및 예제 코드 활용

  새로운 프레임워크(Flet)를 학습할 때는 공식 문서의 Getting Started 가이드나 예제 코드를 최대한 활용하는 것이 좋습니다. 공식 예제는 검증된 코드 패턴을 제공하므로, 이를 기반으로 코드를 작성하면 불필요한 오류를 줄일 수 있습니다.

• 디버깅 습관

  애플리케이션이 예상대로 동작하지 않을 때는 당황하지 않고 디버깅 도구를 활용하여 코드의 흐름을 추적해보세요. print() 문을 활용하여 특정 코드 블록이 실행되는지 확인하는 것도 간단하지만 효과적인 방법입니다.

이 가이드가 Flet 앱 실행 문제를 해결하고 앞으로 더 원활하게 개발하는 데 도움이 되기를 바랍니다. 올바른 if __name__ == "__main__": 사용법을 숙지하여 안정적인 Flet 앱을 만들어 보세요!