Airflow 웹서버 컨테이너를 재시작했는데 아래와 같은 에러가 발생했다.

Error: Already running on PID 42 
(or pid file '/opt/airflow/airflow-webserver.pid' is stale)
```![](https://velog.velcdn.com/images/mason_dev/post/258df9f9-be95-4bf3-bddb-4e7d1b6e4729/image.png)


그리고 `localhost:8080` 접속이 되지 않는 상황.

---

## 📌 문제 원인 분석

Airflow는 웹서버 실행 시 다음 경로에 PID 파일을 생성한다.

/opt/airflow/airflow-webserver.pid

이 파일에는 실행 중인 프로세스 ID(PID)가 기록된다.

하지만 아래와 같은 상황이 발생하면:

* 컨테이너 강제 종료
* `kill -9`
* 비정상 종료
* Docker 재시작 중 충돌

👉 **PID 파일이 삭제되지 않고 남게 된다.**

그 결과 Airflow는:

> “이미 실행 중이다”라고 잘못 판단하고 종료한다.

이를 **stale PID file 문제**라고 한다.

---

## 구조 이해 (추천 이미지)

velog에 아래와 같은 구조 다이어그램 하나 넣으면 이해도가 확 올라간다.

### 📷 추천 이미지 1: Airflow PID 동작 구조

[ airflow webserver 실행 ]
↓
[ airflow-webserver.pid 생성 ]
↓
[ 비정상 종료 ]
↓
[ pid 파일은 남아있음 ]
↓
[ 재실행 시 충돌 발생 ]

(다이어그램 툴: draw.io / Excalidraw 추천)

---

# 해결 방법 1 — 컨테이너 내부에서 직접 해결

### 1️⃣ 실행 중인 컨테이너 확인

```bash
docker ps

---

2️⃣ 컨테이너 접속

docker exec -it <webserver_container_name> bash

---

3️⃣ PID 파일 삭제

rm -f /opt/airflow/airflow-webserver.pid

확인:

ls /opt/airflow | grep pid

---

4️⃣ 웹서버 재실행

airflow webserver

또는 (Airflow 2.x)

airflow webserver --port 8080

---

해결 방법 2 — docker-compose 사용 시 (권장)

Airflow를 docker-compose로 실행 중이라면 통째로 재기동하는 것이 더 깔끔하다.

docker-compose down
docker-compose up -d

그래도 해결되지 않으면:

docker-compose down -v
docker-compose up -d

⚠ -v 옵션은 볼륨 삭제 → DB 초기화됨

---

추가 확인 (실제로 프로세스가 살아있는지 체크)

혹시 진짜 웹서버 프로세스가 떠 있는 경우도 있으니 확인:

ps -ef | grep airflow

실행 중이라면 kill 후 재시작.

---

실무 정리

상황	해결
90% 케이스	PID 파일 삭제
docker-compose 사용	down → up -d
여전히 안 됨	logs 확인

docker logs <webserver_container_name>

---

근본적 예방 방법

1. 컨테이너 강제 종료 지양
2. docker stop 사용
3. 운영 환경에서는 systemd 또는 supervisor 사용
4. healthcheck 설정 고려

---

핵심 한 줄 정리

Airflow Already running on PID 오류는
대부분 stale PID 파일 때문이다.