[FastAPI] Uvicorn 서버 실행 중 자주 만나는 에러와 해결법

 

서론

FastAPI 개발할 때 로컬에서 서버를 실행하려고 하면, 의외로 자주 만나는 에러들이 있다. 특히 uvicorn main:app --reload 같은 기본 커맨드로 실행할 때 생각보다 많은 시행착오를 겪게 된다.

처음에는

"엥? 왜 안켜지지?"

"아까 켜졌는데 왜 안돼?"

"어디가 문제야?"

이런 당황스러운 순간이 온다.

오늘은 내가 직접 FastAPI 개발하면서 겪었던, FastAPI(Uvicorn) 서버 실행 시 가장 자주 만나는 에러와 해결 방법을 정리해보려고 한다.

---

본론

[Errno 48] Address already in use

에러 상황

ERROR: [Errno 48] Address already in use

• 이미 8000번 포트를 누가 쓰고 있다.
• uvicorn 기본 포트가 8000인데, 아까 띄워놓은 서버가 죽지 않고 남아있던 것.

해결 방법

(1) 프로세스 강제 종료

lsof -i :8000

• 터미널에서 위의의 명령어를 실행하면 아래처럼 PID 가 나온다

 

COMMAND   PID       USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
Python  12123 user    user  IPv4 0---      0t0  TCP localhost:irdmi (LISTEN)

• 위의 결과의 PID에 있는 값을 아래 명령어에 입력

 

kill -9 [PID]
kill -9 12123 

• 포트를 다른걸로 바꿔도 되지만, 보통은 깔끔하게 죽이는 게 좋다.

 

---

Error loading ASGI app. Could not import module "main"

에러 상황

ERROR: Error loading ASGI app. Could not import module "main".

• main.py 파일이 현재 디렉토리에 없거나
• 모듈 이름을 잘못 지정했거나
• FastAPI app 인스턴스 이름 (app)을 잘못 선언했을 때 발생.

해결 방법

• 폴더 실행 위치를 다시 확인.
• 명령어 다시 확인:(현재 폴더에 main.py 가 있고, 그 안에 app = FastAPI() 선언이 되어 있어야 함)
• uvicorn main:app --reload

---

ModuleNotFoundError: No module named 'xxx'

에러 상황

ModuleNotFoundError: No module named 'xxx'

• 가상환경(.venv)이 꼬였거나
• 필요한 패키지를 설치 안했거나
• 경로가 꼬였을 때 주로 발생.

해결 방법

• 가상환경 다시 활성화하고

source venv/bin/activate

• requirements.txt 기준 설치:

pip install -r requirements.txt

• 모듈 import 경로 확인.

---

psycopg2.errors.UniqueViolation

에러 상황

psycopg2.errors.UniqueViolation: duplicate key value violates unique constraint

• DB에 중복 데이터 삽입 시도.
• 예를 들어, primary key나 unique 제약조건이 걸려있는 필드에 이미 같은 값이 존재할 때 발생.

해결 방법

• DB 데이터 확인하고 삭제하거나
• 코드에 중복 체크 로직 추가해야 함.

---

결론

FastAPI(Uvicorn) 기반으로 개발하다 보면, 생각보다 단순한 문제로 서버가 안켜지는 경우가 많다.

특히 초반에는

• 포트 충돌
• 모듈 import 경로
• 가상환경 문제
• DB 제약 조건 에러 이런 것들이 진입장벽이 된다.

하지만 몇 번 겪어보면

"아 이건 포트 문제구나"

"아 이건 import 잘못했구나"

하고 예상이 된다.