FastAPI 최신 버전 이후 ‘Cannot add middleware after an application has started’ 오류란?
2026년 8월, FastAPI 프레임워크가 새롭게 업데이트되면서 일부 사용자들은 “Cannot add middleware after an application has started”라는 오류 메시지를 경험하고 있습니다. 이는 FastAPI 내부 미들웨어 추가 과정이 애플리케이션 실행 후에 제한되면서 발생하는 문제로, 특히 웹UI 환경에서 설치 후 실행 단계에서 빈번하게 목격됩니다. 본 글에서는 이 오류의 원인과 근본적인 해결책, 그리고 안정적인 FastAPI 구버전 설치 방법까지 꼼꼼하게 정리하였습니다.
오류 원인과 상세 분석
FastAPI 0.91.0 이상의 버전에서 변경된 내부 미들웨어 처리 로직이 문제의 핵심입니다. 미들웨어를 애플리케이션 실행(스타트) 이후에 추가하려고 하면 이 오류가 발생하며, 이는 FastAPI 자체의 버그 또는 미들웨어 모듈 구현 방식 변화에 기인합니다. 해당 오류는 WebUI 설치 과정에서 특히 두드러지는데, WebUI는 FastAPI를 기반으로 하여 웹서버를 띄우는 구조이기 때문입니다.
이 문제는 FastAPI 최신 버전의 불안정한 업데이트에서 비롯된 것으로 보고 있으며, 따라서 현재 가장 안전한 해결 방법은 FastAPI 0.90.0 이하 버전으로 다운그레이드하는 것입니다.
PowerShell에서 스크립트 실행 권한 설정 방법
FastAPI 구버전 설치를 위해서는 PowerShell에서 스크립트 실행 권한을 우선 변경해줘야 합니다. 기본적으로 PowerShell은 제한된 실행 정책이 적용되어 있기 때문입니다.
- 윈도우 검색창에 “PowerShell”을 입력합니다.
주의: “Windows PowerShell”로 검색하지 말고 반드시 “PowerShell”만 입력해야 합니다. - 검색 결과에서 PowerShell 아이콘을 마우스 오른쪽 클릭 후 “관리자 권한으로 실행”을 선택합니다.
- 관리자 권한 PowerShell 창이 열리면 다음 명령어를 입력합니다:
Set-ExecutionPolicy Unrestricted - 명령어 실행 후 “변경을 수행하시겠습니까?”라는 질문에
y를 입력하고 엔터를 누릅니다.
이제 스크립트 실행 권한이 풀려 구버전 FastAPI를 설치할 준비가 완료되었습니다.
FastAPI 0.90.0 구버전 설치 및 활성화 절차
아래 단계는 WebUI가 이미 설치된 경로를 기준으로 작성되었습니다. 명령어 실행 전 본인의 환경 경로를 꼭 확인하세요.
- PowerShell에서 WebUI 설치 폴더로 이동:
cd [WebUI 설치 경로] - 가상환경 스크립트 폴더로 이동:
cd ./venv/Scripts/ - 가상환경 활성화:
./Activate.ps1 - FastAPI 구버전 설치:
pip install --upgrade fastapi==0.90.0
설치가 완료되면 오류가 발생하지 않고 정상적으로 WebUI가 작동하는지 테스트합니다.
실행 정책 원상복구 방법
구버전 FastAPI 설치가 완료되고 WebUI 테스트가 정상적으로 끝났다면, 보안을 위해 PowerShell 실행 정책을 다시 제한 상태로 돌려놓는 것이 좋습니다.
- 다시 관리자 권한 PowerShell을 실행합니다.
- 다음 명령어를 입력합니다:
Set-ExecutionPolicy Restricted - 변경 여부 확인 시
y를 입력하고 엔터를 눌러 실행 정책을 제한 상태로 복원합니다.
WebUI 실행 확인 및 마무리
이후 webui-user.bat 파일을 실행하면 FastAPI 미들웨어 오류 없이 정상적으로 WebUI가 동작하는 것을 확인할 수 있습니다. 만약 동일 오류가 반복된다면, 위 절차가 올바르게 진행되었는지, 경로 및 권한 설정을 다시 한 번 점검해보시기 바랍니다.
FastAPI 미들웨어 오류 해결 요약표
| 단계 | 명령어 및 작업 | 설명 |
|---|---|---|
| 1 | PowerShell 관리자 권한 실행 | 스크립트 실행 권한 변경을 위해 필요 |
| 2 | Set-ExecutionPolicy Unrestricted | 스크립트 실행 허용 |
| 3 | 가상환경 활성화(./venv/Scripts/Activate.ps1) | FastAPI 설치 환경 진입 |
| 4 | pip install –upgrade fastapi==0.90.0 | FastAPI 구버전 설치 |
| 5 | Set-ExecutionPolicy Restricted | 스크립트 실행 권한 제한 복구 |
FastAPI 버전별 주요 차이 및 영향
| 버전 | 변경 사항 | 오류 발생 여부 |
|---|---|---|
| 0.89.0 이하 | 기존 미들웨어 동작 안정적 | 발생하지 않음 |
| 0.90.0 | 안정화된 구버전, 권장 다운그레이드 타겟 | 해결 가능 |
| 0.91.0 이상 | 미들웨어 처리 로직 변경 | “Cannot add middleware after an application has started” 오류 빈발 |
FastAPI 미들웨어 오류 자주 묻는 질문(FAQ)
Q1: PowerShell 실행 정책을 변경하는 것이 위험하지 않나요?
A: 실행 정책을 “Unrestricted”로 임시 변경하는 것은 스크립트 실행 허용을 의미하지만, 작업 완료 후 반드시 “Restricted”로 복구하는 것이 보안상 안전합니다.
Q2: FastAPI 0.90.0 버전 이외 다른 버전을 설치해도 되나요?
A: 현재 이 오류는 0.91.0 이상 버전에서 주로 발생하므로 0.90.0 버전이 가장 안정적이며 권장됩니다. 다른 버전 사용 시 테스트가 필요합니다.
Q3: WebUI가 아닌 일반 FastAPI 프로젝트에도 동일한 해결법이 적용되나요?
A: 네, FastAPI 미들웨어 관련 오류는 프레임워크 구조 문제이므로 WebUI뿐 아니라 다른 FastAPI 프로젝트에도 같은 버전 다운그레이드 방법이 유용합니다.
마무리 및 업데이트 안내
본 가이드는 2026년 8월 시점 기준 FastAPI 미들웨어 오류를 근본적으로 해결하기 위해 작성되었습니다. 앞으로 FastAPI 공식 패치가 이루어지면 최신 정보를 바로 반영하여 안내해드릴 예정입니다. 오류가 해결된 이후에도 문제가 지속된다면, 공식 FastAPI GitHub 이슈 래포트나 WebUI 개발자 포럼을 참고하시길 권장합니다.
작성 · 정리 기준
- 작성 황금게임코드모아 편집팀 · 게임 코드·공략 정보 정리
- 정리 기준 공개된 게임 코드 자료와 공식 게임 채널 정보를 참고해 정리하고 월 단위로 갱신합니다.
- 이용 안내 코드·수치는 업데이트 시점에 따라 달라질 수 있으니 게임 내에서 최종 확인하시기 바랍니다.