Docker Compose 종료 오류는 네트워크를 사용하는 컨테이너가 남아 있는지부터 확인하는 것이 안전합니다.
Docker Compose에서 docker compose down 실행 중 network has active endpoints 오류가 나오면, 보통 해당 네트워크를 아직 사용하는 컨테이너가 남아 있다는 뜻입니다. 먼저 실행 중 컨테이너와 종료된 컨테이너를 확인하고, 어떤 컨테이너가 네트워크에 붙어 있는지 확인한 뒤 정리해야 합니다.
이 오류가 난다고 바로 docker system prune부터 실행하는 것은 좋지 않습니다. 불필요한 컨테이너나 네트워크뿐 아니라 이미지, 빌드 캐시, 옵션에 따라 볼륨까지 정리될 수 있으므로 현재 프로젝트에 남겨야 할 데이터가 있는지 먼저 확인해야 합니다.
오류 메시지 원문
대표적으로 아래와 같은 메시지가 나타납니다. 문구는 Docker Desktop, 터미널, Compose 버전에 따라 조금 달라질 수 있지만 핵심은 네트워크에 아직 active endpoint가 남아 있다는 점입니다.
error while removing network
network has active endpointsdocker compose down을 실행했는데 컨테이너는 일부 내려간 것처럼 보이고, 마지막에 네트워크 삭제 단계에서 실패하는 형태로 보일 수 있습니다.
docker compose down
Error response from daemon:
error while removing network: network has active endpoints언제 발생하는 오류인지
network has active endpoints는 네트워크 자체보다 그 네트워크를 사용하는 컨테이너 연결 상태를 봐야 하는 오류입니다. Docker 네트워크는 컨테이너가 붙어 있으면 바로 삭제되지 않을 수 있습니다.
| 발생 상황 | 확인할 부분 | 먼저 할 일 |
|---|---|---|
| docker compose down 실행 시 | Compose 프로젝트 컨테이너가 남아 있는지 | docker ps -a 확인 |
| docker network rm 실행 시 | 해당 네트워크를 쓰는 컨테이너가 있는지 | docker network inspect 확인 |
| Docker Desktop에서 삭제 후 | Containers 또는 Networks 화면에 잔여 항목이 있는지 | 같은 프로젝트 이름 검색 |
| 다른 컨테이너가 같은 네트워크 사용 | 수동 실행 컨테이너 또는 다른 Compose 프로젝트 | 네트워크 inspect 결과 확인 |
주요 원인 4가지
이 오류는 Compose 파일 자체가 없거나 포트가 이미 사용 중일 때 나는 compose up 실행 오류와 다릅니다. 여기서는 프로젝트를 종료하거나 네트워크를 정리하는 단계에서 남아 있는 연결을 찾는 것이 핵심입니다.
1. 컨테이너가 아직 실행 중인 경우
서비스 컨테이너가 완전히 종료되지 않았거나, 특정 컨테이너가 재시작 정책 때문에 다시 살아나면 네트워크가 계속 사용 중으로 남을 수 있습니다.
2. 종료된 컨테이너가 네트워크에 남아 있는 경우
컨테이너가 실행 중은 아니더라도 삭제되지 않은 상태로 네트워크 정보를 붙잡고 있을 수 있습니다. 이때는 docker ps만 보면 놓칠 수 있으므로 docker ps -a까지 확인해야 합니다.
3. orphan container가 남아 있는 경우
Compose 파일에서 서비스 이름을 바꾸거나 일부 서비스를 제거한 뒤 이전 컨테이너가 남으면 orphan container가 될 수 있습니다. 이 경우 일반 docker compose down만으로 정리가 안 되는 것처럼 보일 수 있습니다.
4. 다른 프로젝트나 수동 실행 컨테이너가 같은 네트워크를 쓰는 경우
수동으로 실행한 컨테이너를 Compose 네트워크에 붙였거나, 여러 Compose 프로젝트가 같은 external network를 쓰면 네트워크 삭제가 막힐 수 있습니다. 이때는 삭제하려는 네트워크가 정말 현재 프로젝트 전용인지 확인해야 합니다.
빠른 해결 순서
먼저 컨테이너를 확인하고, 이어서 네트워크와 연결된 컨테이너를 확인한 뒤 Compose 종료를 다시 실행합니다. 삭제 명령은 원인을 확인한 뒤 필요한 범위에서만 사용합니다.
| 순서 | 명령어 | 확인 목적 |
|---|---|---|
| 1 | docker ps | 실행 중 컨테이너 확인 |
| 2 | docker ps -a | 종료된 컨테이너까지 확인 |
| 3 | docker network ls | 남아 있는 네트워크 이름 확인 |
| 4 | docker network inspect | 네트워크를 쓰는 컨테이너 확인 |
| 5 | docker compose down | 프로젝트 정상 종료 재시도 |
| 6 | docker compose down --remove-orphans | 남은 orphan container 정리 |
| 7 | docker network rm | 마지막 수단으로 네트워크 직접 삭제 |
사용 명령어와 처리 순서
1. 실행 중 컨테이너 확인
먼저 아직 실행 중인 컨테이너가 있는지 확인합니다. 여기에서 해당 프로젝트 컨테이너가 보이면 먼저 종료 대상인지 판단해야 합니다.
docker ps2. 종료된 컨테이너까지 확인
실행 중 컨테이너가 없더라도 종료된 컨테이너가 네트워크에 남아 있을 수 있습니다. 그래서 -a 옵션으로 전체 컨테이너를 확인합니다.
docker ps -a컨테이너 이름에 프로젝트 폴더명이나 Compose 서비스명이 포함되어 있는지 봅니다. 예를 들어 myapp-web-1, myapp-db-1처럼 보일 수 있습니다.
3. 네트워크 목록 확인
삭제가 실패한 네트워크 이름을 확인합니다. Compose 기본 네트워크는 보통 프로젝트명_default 형식으로 만들어지는 경우가 많습니다.
docker network ls4. 특정 네트워크를 사용하는 컨테이너 확인
오류가 난 네트워크를 정확히 찾았다면 inspect로 어떤 컨테이너가 연결되어 있는지 확인합니다. 결과의 Containers 영역에 컨테이너 ID나 이름이 남아 있으면 네트워크가 아직 사용 중입니다.
docker network inspect 네트워크이름5. compose down 다시 실행
프로젝트 폴더가 맞는지 확인한 뒤 다시 docker compose down을 실행합니다. 다른 폴더에서 실행하면 다른 Compose 프로젝트로 인식될 수 있습니다.
docker compose down6. orphan container가 의심될 때
서비스 이름을 바꿨거나 Compose 파일에서 서비스를 제거한 뒤 오류가 이어지면 orphan container가 남아 있을 수 있습니다. 이때만 --remove-orphans 옵션을 사용합니다.
docker compose down --remove-orphans7. 남은 컨테이너 직접 삭제
삭제 전 확인
아래 명령어는 컨테이너를 삭제합니다. 해당 컨테이너가 현재 프로젝트에서 더 이상 필요 없는지, 컨테이너 안에 남겨야 할 데이터가 없는지 확인한 뒤 실행해야 합니다.
docker rm 컨테이너이름8. 마지막으로 네트워크 직접 삭제
마지막 수단으로 사용
네트워크 직접 삭제는 해당 네트워크를 사용하는 컨테이너가 모두 정리된 뒤 실행해야 합니다. 다른 프로젝트가 함께 쓰는 external network라면 삭제하지 않는 것이 안전합니다.
docker network rm 네트워크이름주의해야 할 삭제·정리 명령어
아래 명령어들은 문제 해결에 도움이 될 수 있지만, 범위가 넓거나 데이터 삭제 위험이 있습니다. 단순히 network has active endpoints 오류가 난다는 이유만으로 바로 실행하지 않는 것이 좋습니다.
docker network prune
실행 전 주의
docker network prune은 사용되지 않는 Docker 네트워크를 한꺼번에 정리합니다. 현재 어떤 네트워크가 남아 있는지, 다른 개발 프로젝트에서 다시 사용할 네트워크가 아닌지 확인한 뒤 실행해야 합니다.
docker network prunedocker system prune
실행 전 주의
docker system prune은 중지된 컨테이너, 사용하지 않는 네트워크, 이미지, 빌드 캐시 등을 넓은 범위로 정리합니다. 단일 네트워크 오류 해결용으로 바로 쓰기에는 범위가 크므로, 필요한 항목을 먼저 확인한 뒤 사용해야 합니다.
docker system prunedocker compose down -v
볼륨 삭제 주의
docker compose down -v는 Compose 프로젝트 종료와 함께 볼륨까지 삭제할 수 있습니다. 데이터베이스, 업로드 파일, 로컬 테스트 데이터가 볼륨에 있다면 사라질 수 있으므로 개발 DB를 초기화해도 되는 상황에서만 사용해야 합니다.
docker compose down -vWindows, Mac, Linux에서 확인할 차이
명령어는 대부분 같지만 Docker가 실행되는 방식은 운영체제별로 다릅니다. Docker Desktop을 쓰는 Windows와 Mac은 내부 VM 또는 WSL2 상태까지 함께 확인할 때가 있습니다.
| 환경 | 자주 보는 상황 | 확인할 것 |
|---|---|---|
| Windows | Docker Desktop과 WSL2 환경에서 컨테이너가 남아 있음 | Docker Desktop Containers 탭, WSL 터미널의 docker ps -a |
| Mac | Docker Desktop 내부 VM 상태와 대시보드 표시가 엇갈림 | Docker Desktop 재시작 전 CLI 결과 확인 |
| Linux | Docker Engine 권한 또는 daemon 상태 문제와 함께 발생 | 현재 사용자 권한, Docker daemon 실행 상태 |
Docker Desktop에서 확인할 것
터미널 명령어와 함께 Docker Desktop 화면도 확인하면 남은 컨테이너를 찾기 쉽습니다. 특히 초보자는 CLI에서 네트워크 이름만 보고 놓치는 컨테이너를 Docker Desktop의 프로젝트 묶음에서 찾을 수 있습니다.
Docker Desktop 확인 체크리스트
Containers 탭에서 실행 중 컨테이너와 종료된 컨테이너를 확인합니다. Images, Volumes, Networks 화면에서 같은 프로젝트 이름이 붙은 항목이 남아 있는지도 봅니다. 특히 Compose 프로젝트 이름이 같은 컨테이너, 수동으로 실행했지만 같은 네트워크에 붙은 컨테이너가 있는지 확인해야 합니다.
재발 방지 체크리스트
이 오류는 한 번 해결해도 프로젝트 이름, 수동 컨테이너 실행, orphan container 관리가 섞이면 다시 발생할 수 있습니다. 종료할 때는 프로젝트 폴더와 Compose 파일 기준을 맞추는 습관이 중요합니다.
| 체크 항목 | 이유 | 권장 방식 |
|---|---|---|
| 프로젝트 폴더에서 명령어 실행 | Compose 프로젝트 인식이 달라질 수 있음 | compose.yaml이 있는 폴더에서 실행 |
| project name 확인 | 네트워크와 컨테이너 이름에 영향을 줌 | 팀 프로젝트에서는 이름 규칙 통일 |
| 수동 컨테이너와 Compose 컨테이너 구분 | 같은 네트워크 사용 시 삭제가 막힐 수 있음 | 수동 컨테이너는 별도 네트워크 사용 |
| 종료할 때 compose down 우선 사용 | 컨테이너와 네트워크를 함께 정리하기 쉬움 | 개별 삭제보다 Compose 명령어 우선 |
공식 자료로 더 확인하기
Docker 명령어 옵션은 버전과 실행 환경에 따라 표시 방식이 달라질 수 있습니다. 삭제나 정리 명령어를 실행하기 전에는 공식 문서에서 옵션 범위를 확인하는 것이 안전합니다.
docker compose down이 어떤 컨테이너, 네트워크, 볼륨을 정리하는지와 --remove-orphans, -v 옵션을 확인할 수 있습니다.
Docker 네트워크 목록, inspect, remove, prune 명령어의 역할과 네트워크 삭제 조건을 확인할 수 있습니다.
Docker network 명령어 확인하기Docker Desktop Dashboard에서 컨테이너, 이미지, 볼륨, 네트워크 등 로컬 Docker 리소스를 확인하는 방법을 볼 수 있습니다.
Docker Desktop 대시보드 확인하기함께 보면 좋은 글
docker compose up 실행 시작부터 막힌다면 Compose 파일 경로와 파일명을 먼저 확인해야 합니다.
network has active endpoints가 아니라 포트가 이미 사용 중이라는 메시지가 나온다면 포트 점유 프로세스와 Compose 포트 매핑을 확인해야 합니다.
docker system prune보다 빌드 캐시 정리 범위를 따로 확인하는 것이 좋습니다.
자주 묻는 질문
Docker compose down의 network has active endpoints 오류는 네트워크를 지우기 전에 어떤 컨테이너가 아직 연결되어 있는지 확인하고, 필요한 컨테이너만 안전하게 정리하는 것이 핵심입니다.
댓글