Docker Compose: network not found

안녕하세요, BlueByte입니다. 어제까지 되던 프로젝트에서 docker compose up을 실행했는데 network-not-found 오류로 멈춥니다 — network <name> declared as external, but could not be found이거나, 컨테이너를 시작하려다 뜨는 Error response from daemon: network <hash> not found입니다. compose 파일은 바뀌지 않았는데, 컨테이너가 기대하는 네트워크가 더 이상 없는 것입니다. 오늘은 두 메시지 형태, Compose가 네트워크를 어떻게 이름 짓고 만드는지, 왜 하나가 사라지는지, 실제로 무엇이 있는지 보는 법, 그리고 경우별 해결까지 하나씩 짚어보겠습니다.

Compose가 출력하는 두 가지 "network not found" 메시지

이 오류를 만드는 상황은 둘로 나뉩니다. 첫째는 없어진 external 네트워크입니다:

network shared_net declared as external, but could not be found

compose 파일이 어떤 네트워크를 external: true로 표시하면, Compose에게 자신이 관리하지 않는 네트워크에 붙으라고 지시하는 것인데 — 그 네트워크가 아직 없는 것입니다. 둘째는 dangling 네트워크 참조입니다:

Error response from daemon: network 7b2a...f31 not found

여기서는 Compose 또는 앞서 만든 컨테이너가 이미 삭제된 네트워크를 ID로 여전히 참조합니다. docker compose up, down, start, restart에서 마주치며 — 저장된 참조가 데몬에 더 이상 없는 네트워크를 가리키는 것입니다.

Compose가 기본 네트워크를 이름 짓고 만드는 방식

docker compose up을 실행하면 Compose는 <project>_default라는 네트워크를 만들어 모든 서비스를 붙입니다. 프로젝트 이름은 compose 파일이 있는 디렉터리에서 오며, 재정의하지 않는 한 그렇습니다:

docker compose -p myproj up -d       # 또는 COMPOSE_PROJECT_NAME=myproj 설정

[+] Running 2/2
 ✔ Network myproj_default   Created
 ✔ Container myproj-web-1   Started

그래서 myapp_default는 myapp 프로젝트의 것입니다. 디렉터리 이름을 바꾸거나 프로젝트 이름을 바꾸면 Compose는 다르게 이름 붙은 네트워크를 찾기 시작하는데 — 실제로는 아무것도 지우지 않았는데 네트워크가 "사라진" 것처럼 보이는 흔한 이유입니다.

네트워크가 사라진 이유

참조가 깨지는 구체적인 원인은 몇 가지입니다:

• 누군가 docker network prune 또는 docker network rm을 실행해, 멈춘 컨테이너가 여전히 가리키는 네트워크를 제거함.
• Docker 데몬이나 호스트가 재시작됐고, 옛 컨테이너 메타데이터가 기대하는 방식으로 네트워크가 다시 만들어지지 않음.
• compose 파일이 생성된 적 없는 external: true 네트워크를 선언했거나, 다른 이름으로 만들어짐.
• 프로젝트 이름이 바뀜 — 디렉터리를 바꿨거나 -p를 추가해 — 이제 Compose는 newname_default를 찾는데 컨테이너는 oldname_default에 붙어 있음.

어떤 네트워크가 있고 프로젝트가 무엇을 기대하는지 확인하기

데몬이 실제로 가진 것을 나열한 뒤, compose 파일이 요구하는 것을 확인하세요:

docker network ls
docker compose config --networks

docker network ls는 모든 네트워크를 이름과 ID로 보여주고, docker compose config --networks는 병합된 compose 파일이 기대하는 네트워크를 출력합니다. 둘째 목록의 이름이 첫째에 없다면 그것이 빈틈입니다. 멈춘 컨테이너가 어떤 네트워크에 묶여 있는지 보려면:

docker inspect -f '{{json .NetworkSettings.Networks}}' myproj-web-1

dangling 네트워크 고치기: 내렸다가 다시 만들기

dangling 참조 경우라면, 프로젝트를 내려 Compose가 네트워크를 다시 세우게 하세요. --remove-orphans는 이전 프로젝트 이름에서 남은 컨테이너도 정리합니다:

docker compose down --remove-orphans
docker compose up -d

down 자체가 같은 네트워크 오류로 실패하면, 컨테이너를 강제로 다시 만들어 새 네트워크에 붙게 하세요:

docker compose up -d --force-recreate

 ✔ Network myproj_default   Created
 ✔ Container myproj-web-1   Recreated

없어진 external 네트워크 고치기: 먼저 만들기

external: true 네트워크는 docker compose up 전에 존재해야 합니다. 한 번 만든 뒤 프로젝트를 올리세요:

docker network create shared_net
docker compose up -d

이름은 정확히 일치해야 합니다. compose 파일이 네트워크에 커스텀 name:을 부여했다면, 키가 아니라 그 이름을 만드세요:

networks:
  shared_net:
    external: true
    name: company_shared

여기서는 docker network create company_shared를 실행해야 합니다 — Compose는 company_shared를 조회하고, shared_net은 로컬 별칭일 뿐입니다.

실제 사례: 호스트 재부팅 뒤 prune된 네트워크

작은 스택이 몇 주째 떠 있었습니다. 호스트를 재부팅한 뒤 공간을 확보하려고 docker system prune을 실행했는데, 멈춰 있던 프로젝트의 네트워크가 제거됐습니다. 그 뒤 docker compose up -d가 network 7b2a...f31 not found로 실패했습니다. docker network ls로 myproj_default가 사라졌음을 확인했습니다. docker compose down --remove-orphans가 낡은 참조를 정리했고, docker compose up -d가 myproj_default를 다시 만들어 두 컨테이너를 재연결했으며, 스택이 되살아났습니다 — compose 파일 수정 없이, 프로젝트 네트워킹을 깨끗한 상태로 되돌린 것뿐입니다.

"network already exists"·"port is already allocated"와 어떻게 다른가

network not found는 부재의 경우입니다 — Compose가 기대하는 네트워크가 없습니다. network <name> ... already exists는 반대로, 같은 이름의 남은 네트워크가 생성을 막는 것이라 docker network rm으로 제거합니다. Bind for 0.0.0.0:8080 failed: port is already allocated는 네트워크와 무관하며 — 다른 프로세스가 발행된 호스트 포트를 점유한 것입니다. 셋 중 무엇을 받았는지 읽으면 네트워크를 만들지, 제거할지, 포트를 비울지가 갈립니다.