Docker Compose 오류 해결 가이드: 자주 발생하는 5가지 문제와 해결 방법

금요일 오후 3시 30분, 코드 제출 마감까지 두 시간이 남았습니다.

터미널에는 빨간색 오류가 떠 있습니다. Error starting userland proxy: Bind for 0.0.0.0:8080 failed: port is already allocated. 어제까지만 해도 잘 실행됐는데 오늘은 시작조차 되지 않습니다.

Ctrl+C를 누르고 다시 실행해 봅니다. 여전히 같은 오류입니다. Google에서 “docker compose port already allocated”를 검색하고 Stack Overflow 게시물 대여섯 개를 열어 해결 방법을 하나씩 시도합니다. Docker를 다시 시작하고, 컨테이너를 삭제하고, 포트를 바꿔 봐도 화면의 오류는 그대로입니다.

Docker Compose 오류 메시지는 수십 줄에 이르는 경우가 많습니다. 정작 필요한 한 문장은 23번째 줄에 숨어 있는데 첫 줄부터 당황하기 쉽습니다. 이 글에는 지난 2년 동안 직접 겪은 문제를 바탕으로 가장 흔한 Docker Compose 오류 5가지를 정리했습니다. 각 오류를 “오류 형태 → 원인 → 해결 방법” 순서로 설명합니다. 어디서부터 확인해야 하는지만 알면 실제로 오류의 90%는 5분 안에 해결할 수 있습니다.

점검의 기본 - 핵심 도구 3가지 익히기

구체적인 오류를 바로 해결하려 들기 전에 Docker Compose 문제를 점검할 때 사용하는 세 가지 기본 명령부터 살펴보겠습니다. 저는 이 명령들을 하루에도 열 번 넘게 사용합니다.

도구 1: docker-compose ps - 상태를 빠르게 확인하기

이 명령은 어떤 컨테이너가 실행 중이고 어떤 컨테이너가 중단됐는지 알려 줍니다.

docker-compose ps

State 열을 확인하세요.

• Up - 정상적으로 실행 중입니다.
• Exit - 시작에 실패했거나 실행 중 비정상 종료됐습니다.
• Restarting - 계속 다시 시작됩니다. 시작 명령에 문제가 있다는 뜻입니다.

저는 어떤 서비스가 Exit 1 상태인 것을 확인하면 바로 로그를 살펴봅니다.

도구 2: docker-compose logs - 로그에서 단서 찾기

오류 점검의 핵심입니다.

# 모든 서비스의 로그 확인
docker-compose logs

# nginx 로그만 확인
docker-compose logs nginx

# 실시간 추적(tail -f와 비슷함)
docker-compose logs -f

# 최근 100줄만 확인
docker-compose logs --tail 100 nginx

솔직히 Docker 로그 출력이 다소 어수선할 때도 있습니다. 하지만 오류의 90%는 마지막 수십 줄에 진짜 원인이 나타납니다. 위쪽으로 올라가며 ERROR, failed, cannot 같은 키워드를 찾으세요.

도구 3: docker inspect - 상세 점검(필요할 때만 사용)

앞의 두 명령으로 해결되지 않을 때 사용합니다.

# 컨테이너 전체 설정 확인
docker inspect 컨테이너명

# 상태만 확인
docker inspect --format='{{.State.Status}}' 컨테이너명

# IP 주소 확인
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' 컨테이너명

공통 점검 절차(기억해 두세요)

문제가 생겨도 당황하지 말고 다음 순서로 확인하세요.

1. docker-compose ps - 어떤 서비스가 중단됐는지 확인합니다.
2. docker-compose logs [서비스명] - 구체적인 오류를 확인합니다.
3. docker inspect - 상세하게 분석합니다(대부분은 여기까지 필요하지 않습니다).

도구를 준비했으니 이제 자주 발생하는 오류 5가지를 살펴보겠습니다.

포트 충돌 - “port is already allocated”

정말 자주 마주치는 오류입니다. 다음과 비슷한 메시지가 표시됩니다.

Error starting userland proxy: Bind for 0.0.0.0:8080 failed: port is already allocated

또는 다음과 같이 나타납니다.

ERROR: for nginx  Cannot start service nginx: driver failed programming external connectivity on endpoint xxx: Bind for 0.0.0.0:80 failed: port is already allocated

왜 이런 문제가 생기나요?

대개 다음 세 가지 중 하나가 원인입니다.

1. 이전에 docker-compose up을 실행한 뒤 Ctrl+C를 눌렀지만 docker-compose down을 실행하지 않아 컨테이너가 백그라운드에서 계속 실행 중입니다.
2. docker-compose.yml의 포트 설정을 바꿨지만 기존 컨테이너를 완전히 삭제하지 않았습니다.
3. 컴퓨터의 다른 프로그램이 해당 포트를 사용 중입니다(예: 로컬 Nginx, MySQL).

해결 방법(간단한 것부터 차례로 시도)

방법 1: 정리한 뒤 다시 시작하기(90%는 해결됨)

docker-compose down
docker-compose up -d

저는 이 방법으로 대부분 해결했습니다. down 명령은 모든 컨테이너를 중지하고 삭제하지만 volume 데이터는 유지합니다.

방법 2: 포트를 사용 중인 컨테이너 찾기

방법 1로 해결되지 않는다면 현재 프로젝트에 속하지 않지만 포트를 사용 중인 이른바 “유령 컨테이너”가 있을 수 있습니다.

# 중지된 컨테이너를 포함해 모든 컨테이너 나열
docker ps -a | grep 8080

# container_id를 찾은 뒤 중지하고 삭제
docker stop <container_id>
docker rm <container_id>

방법 3: docker-proxy 프로세스 확인하기

컨테이너를 삭제했는데도 docker-proxy 프로세스가 남아 있을 때가 있습니다.

# docker-proxy 프로세스 확인
ps aux | grep docker-proxy | grep 8080

# 프로세스가 남아 있으면 Docker 서비스 다시 시작
sudo systemctl restart docker  # Linux
# Mac에서는 Docker Desktop 메뉴 → Restart

방법 4: 호스트 포트 사용 여부 확인하기

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

로컬 프로그램이 포트를 사용하고 있을 수도 있습니다.

# Linux/Mac
lsof -i :8080
netstat -tlnp | grep 8080

# Windows
netstat -ano | findstr 8080

다른 프로그램이 사용 중이라면 해당 프로그램을 중지하거나 docker-compose.yml의 포트를 변경하세요.

방법 5: 포트 설정 변경하기(다른 방법이 없을 때)

docker-compose.yml을 편집합니다.

services:
  web:
    ports:
      - "8081:80"  # 8080을 8081로 변경

권장 사항

컨테이너를 중지할 때는 Ctrl+C만 누르지 말고 docker-compose down을 사용하는 습관을 들이세요. 예전에는 편하다는 이유로 늘 Ctrl+C만 눌렀고 며칠에 한 번꼴로 포트 충돌이 났습니다. 습관을 바꾼 뒤로는 이 오류가 거의 사라졌습니다.

개발 환경에서는 가능하면 표준 포트를 피하세요. 80이나 3306을 그대로 쓰지 말고 8080이나 3307을 사용하면 시스템 서비스와의 충돌을 줄일 수 있습니다.

네트워크 문제 - “network declared as external but could not be found”

이 오류는 보통 다음과 같이 나타납니다.

ERROR: Network my_network declared as external, but could not be found. Please create the network manually using `docker network create my_network` and try again.

왜 이 오류가 발생하나요?

Docker Compose에는 놓치기 쉬운 부분이 있습니다. docker-compose.yml에서 어떤 네트워크를 external: true로 표시하면 Docker는 해당 네트워크가 이미 존재한다고 가정하고 자동으로 만들지 않습니다. 네트워크를 찾지 못하면 오류가 발생합니다.

흔한 상황은 다음과 같습니다.

1. 다른 사람의 설정 파일을 복사했는데 external 네트워크가 로컬에 없습니다.
2. Docker를 다시 시작한 뒤 일부 네트워크 설정이 사라졌습니다.
3. 네트워크 이름의 대소문자가 잘못됐습니다(Docker 네트워크 이름은 대소문자를 구분합니다!).

해결 방법

방법 1: 기존 네트워크를 나열하고 이름 확인하기

docker network ls

설정에 적힌 app_network가 아니라 실제 네트워크 이름이 myproject_app_network일 수도 있습니다. Docker Compose는 네트워크에 프로젝트 이름 접두사를 자동으로 붙입니다.

방법 2: 누락된 네트워크를 수동으로 만들기

네트워크가 실제로 없다면 생성합니다.

docker network create my_network

방법 3: 설정 파일 수정하기

다음 세 가지 중 한 가지를 선택하세요.

# 방법 A: external을 제거하고 Compose가 자동으로 생성하게 함
networks:
  app_network:
    driver: bridge

# 방법 B: name 필드로 네트워크 이름을 명시
networks:
  app_network:
    external: true
    name: my_actual_network_name

# 방법 C: 네트워크를 먼저 수동으로 만들고 external로 참조

저는 방법 A를 선호합니다. 여러 Compose 프로젝트에서 네트워크를 공유해야 하는 경우가 아니라면 Compose가 네트워크를 관리하게 하는 편이 간단합니다.

방법 4: 정리하고 다시 생성하기(Docker 재시작 후 네트워크가 사라진 경우)

docker-compose down
docker network prune  # 사용하지 않는 네트워크 정리
docker-compose up -d

문제 예방 방법

• 어떤 네트워크가 external이어야 하는지(프로젝트 간 공유), 어떤 네트워크를 Compose가 관리해야 하는지(단일 프로젝트 사용) 명확히 구분하세요.
• name 필드로 네트워크 이름을 명시해 Compose의 자동 접두사 때문에 생기는 혼동을 방지하세요.
• 팀 README에 미리 생성해야 하는 external 네트워크를 기록해 새 구성원이 같은 문제를 겪지 않게 하세요.

빌드 실패 - “service failed to build”

다음 오류가 보여도 당황하지 마세요.

ERROR: Service 'app' failed to build: Build failed

핵심 요령: 로그를 위로 올려 보기

“service failed to build”는 요약 오류일 뿐입니다. 실제 문제는 앞부분에 있습니다. 50~100줄 위로 올라가 ERROR, failed, cannot, not found, permission denied 같은 키워드를 찾으세요.

이 오류를 처음 봤을 때 마지막 줄만 한참 들여다봤습니다. 나중에야 위쪽 로그를 확인해야 한다는 사실을 알았습니다. 실제 오류는 “npm install 실패”나 “파일을 찾을 수 없음”일 수 있으며 많은 출력 사이에 숨어 있습니다.

자주 발생하는 하위 오류 유형

유형 1: 파일을 찾을 수 없음

COPY failed: stat /var/lib/docker/tmp/.../package.json: no such file or directory

원인:

• build context 경로가 잘못됐습니다.
• .dockerignore에서 필요한 파일을 제외했습니다.

해결 방법:

# docker-compose.yml의 context 설정 확인
services:
  app:
    build:
      context: ./my-app  # 경로가 올바른지 확인
      dockerfile: Dockerfile

# 테스트를 위해 .dockerignore 이름을 임시로 변경
mv .dockerignore .dockerignore.bak
docker-compose build app

유형 2: 종속성 설치 실패

npm ERR! 404 Not Found - GET https://registry.npmjs.org/xxx

또는 다음과 같이 나타납니다.

E: Unable to locate package xxx

원인: 패키지 이름 오류, 존재하지 않는 버전, 네트워크 문제

해결 방법:

# 중국 내 미러 사용(Dockerfile에서 설정)
RUN npm config set registry https://registry.npmmirror.com
RUN npm install

# 또는 apt 미러 변경
RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list
RUN apt-get update && apt-get install -y xxx

유형 3: 메모리 부족

The command '/bin/sh -c npm install' returned a non-zero code: 137
signal: killed

이 137 종료 코드는 보통 메모리가 부족하다는 뜻입니다.

해결 방법:

• Docker Desktop → Settings → Resources → Memory에서 4GB 이상으로 조정합니다.
• 또는 Dockerfile에서 동시 빌드를 줄입니다: RUN npm install --max_old_space_size=4096.

유형 4: Dockerfile 구문 오류

명령 이름이 잘못됐거나 COPY의 원본 파일 경로가 틀린 경우입니다.

해결 방법: 별도로 빌드해 테스트합니다.

cd 빌드_디렉터리
docker build -t test-build .

이렇게 하면 오류 정보를 더 명확하게 확인할 수 있습니다.

디버깅 방법

캐시를 사용하지 않고 다시 빌드하기:

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

docker-compose build --no-cache service_name

캐시된 중간 레이어에 문제가 생길 때가 있습니다. 캐시를 지우고 다시 빌드하면 해결되기도 합니다.

빌드 컨텍스트 확인하기:

docker-compose config

이 명령은 Compose가 해석한 전체 설정을 보여 주므로 경로 문제를 찾는 데 도움이 됩니다.

경험에서 얻은 요령

• 정상적으로 빌드되는 버전을 baseline으로 보관하고 변경할 때마다 테스트한 뒤 다음 작업을 진행하세요.
• Dockerfile은 한 번에 조금씩만 수정하세요. 여러 부분을 한꺼번에 바꾸면 오류가 발생했을 때 원인을 찾기 어렵습니다.
• 빌드가 느리다면 다단계 빌드를 사용하거나 명령 순서를 조정하세요. 자주 바뀌지 않는 명령을 앞쪽에 두면 캐시를 활용할 수 있습니다.

컨테이너 시작 직후 종료 - “exited with code X”

이 상황은 더 알아채기 어렵습니다. 이미지 빌드는 성공하고 컨테이너도 시작되지만 곧바로 종료됩니다.

docker-compose ps를 실행하면 다음과 같이 표시됩니다.

Name              State
app_web_1         Exit 1
app_db_1          Up

종료 코드의 의미(다음 항목은 기억해 두세요)

• Exit 0: 프로그램이 정상적으로 종료됐습니다. 하지만 컨테이너에서는 문제가 될 수 있습니다(명령 실행이 끝나면 컨테이너도 종료됨).
• Exit 1: 애플리케이션 오류입니다(가장 흔함).
• Exit 137: 메모리 부족(OOM) 또는 kill 처리됐습니다.
• Exit 139: 세그멘테이션 오류(Segmentation fault)입니다.
• Exit 143: SIGTERM 신호를 받았습니다(일반적으로 수동 중지).

점검 단계

1단계: 로그 확인하기

docker-compose logs service_name

90%의 경우 로그에서 종료 원인을 확인할 수 있습니다.

2단계: 컨테이너에 직접 들어가 디버깅하기

로그만으로 문제를 알 수 없다면 컨테이너가 계속 실행되도록 docker-compose.yml을 변경합니다.

services:
  app:
    command: sleep infinity  # 우선 컨테이너가 종료되지 않게 함

그런 다음 다음 명령을 실행합니다.

docker-compose up -d
docker-compose exec app sh  # 컨테이너 진입
# 기존 시작 명령을 직접 실행해 오류 확인

상황별 해결 방법

Exit 0 - 명령 실행 후 컨테이너 종료

예를 들어 command가 echo "Hello"라면 명령 실행 후 할 일이 없어 컨테이너가 자연스럽게 종료됩니다.

해결 방법: 데몬이나 블로킹 명령으로 바꿉니다.

# 잘못된 예
command: echo "Started"

# 올바른 예
command: npm start  # 계속 실행되는 프로세스

Exit 1 - 애플리케이션 오류

로그에서 구체적인 원인을 찾으세요. 자주 발생하는 원인은 다음과 같습니다.

• 설정 파일 경로 오류
• 환경 변수 누락
• 데이터베이스 연결 실패(데이터베이스가 아직 ready 상태가 아님)
• 권한 문제

Exit 137 - 메모리 부족

컨테이너에 메모리 제한을 추가합니다.

services:
  app:
    mem_limit: 2g
    memswap_limit: 2g

또는 Docker Desktop의 전체 메모리 할당량을 조정합니다.

종속 서비스가 준비되지 않음

저도 이 문제를 겪은 적이 있습니다. 애플리케이션 컨테이너가 시작됐지만 데이터베이스가 아직 초기화 중이라 연결하지 못하고 종료됐습니다.

해결 방법: depends_on과 healthcheck를 함께 사용합니다.

services:
  app:
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

이렇게 하면 db가 실제로 ready 상태가 된 뒤 app이 시작됩니다.

직접 겪은 문제

한번은 컨테이너가 계속 Exit 1 상태가 됐고 로그에는 “Config file not found”라는 한 줄만 있었습니다. 한참 찾은 끝에 설정 파일 위치를 상대 경로로 적었지만 컨테이너의 작업 디렉터리가 예상과 달랐다는 사실을 발견했습니다. 절대 경로로 바꾸자 해결됐습니다.

또 한 번은 데이터베이스 비밀번호를 잘못 입력해 애플리케이션이 시작하자마자 종료됐습니다. 로그에는 원인이 명확하게 적혀 있었는데 제대로 읽지 않아 20분을 낭비했습니다.

권한 문제 - “permission denied”

volume을 마운트할 때 특히 자주 발생합니다.

Error: EACCES: permission denied, open '/app/data/config.json'

컨테이너 로그에 “Permission denied”라고만 표시되어 어떤 파일이 문제인지 알기 어려울 때도 있습니다.

권한 문제는 왜 발생하나요?

컨테이너 내부 사용자의 UID/GID가 호스트 파일 소유자와 일치하지 않기 때문입니다. 예를 들면 다음과 같습니다.

• 호스트 파일 소유자는 현재 사용자입니다(UID 1000).
• 컨테이너 안의 애플리케이션은 www-data 사용자로 실행됩니다(UID 33).
• www-data에는 해당 파일을 읽고 쓸 권한이 없어 오류가 발생합니다.

해결 방법

방법 1: user로 UID/GID 지정하기(권장)

컨테이너를 현재 사용자 권한으로 실행합니다.

services:
  app:
    user: "${UID}:${GID}"
    volumes:
      - ./data:/app/data

실행할 때는 다음과 같이 입력합니다.

UID=$(id -u) GID=$(id -g) docker-compose up

또는 .env 파일에 저장합니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

# .env
UID=1000
GID=1000

방법 2: 호스트 파일 권한 변경하기

간단하지만 강제적인 방법입니다.

chmod -R 777 ./data  # 주의해서 사용해야 하며 보안 위험이 있음
# 또는
chmod -R 755 ./data  # 더 안전함
chown -R $(id -u):$(id -g) ./data

방법 3: SELinux 시스템(CentOS/RHEL)에 플래그 추가하기

CentOS/RHEL을 사용한다면 SELinux 제한이 원인일 수 있습니다.

volumes:
  - ./data:/app/data:z  # 여러 컨테이너가 공유하도록 허용
  # 또는
  - ./config:/app/config:Z  # 이 컨테이너만 사용

소문자 z와 대문자 Z의 차이는 소문자는 공유 권한, 대문자는 전용 권한이라는 점입니다.

방법 4: bind mount 대신 named volume 사용하기

Docker가 관리하는 volume에는 권한 문제가 발생하지 않습니다.

services:
  app:
    volumes:
      - app_data:/app/data  # named volume

volumes:
  app_data:  # Docker가 권한을 자동 관리

단점은 호스트에서 파일을 직접 수정할 수 없고 컨테이너를 통해 접근해야 한다는 것입니다.

방법 5: entrypoint 스크립트에서 권한 조정하기

복잡한 상황에 적합합니다.

# entrypoint.sh
#!/bin/sh
chown -R appuser:appuser /app/data
exec "$@"

COPY entrypoint.sh /
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["node", "app.js"]

권장 사항

• 프로덕션 환경: named volume을 사용하세요. 안전하며 권한을 따로 관리할 필요가 없습니다.
• 개발 환경: 방법 1(user로 UID/GID 지정)을 사용하세요. 호스트에서 파일을 직접 수정하기 편합니다.
• 777 권한 피하기: 컨테이너에서 실행되는 코드를 완전히 신뢰하는 경우가 아니라면 777 권한을 부여하지 마세요.

권한 문제는 다소 복잡해 보이지만 UID/GID가 일치해야 한다는 원리를 이해하면 어렵지 않습니다.

공통 디버깅 방법 정리

구체적인 오류를 살펴봤으니 마지막으로 체계적인 점검 방법을 정리하겠습니다.

표준 점검 절차(순서대로 따라 하세요)

1. docker-compose ps             → 상태를 보고 문제가 있는 서비스 확인
2. docker-compose logs <서비스>  → 로그를 보고 핵심 오류 정보 찾기
3. docker-compose config         → 설정 파일 구문 검증
4. docker inspect <컨테이너>     → 상세 점검(필요한 경우)
5. 격리 테스트                  → 문제가 있는 서비스를 따로 시작

이 순서를 습관으로 만들면 문제가 생겨도 막막하지 않습니다.

자주 쓰는 정리 명령(정기적으로 대청소하기)

# 컨테이너를 중지하고 삭제(volume은 유지)
docker-compose down

# volume까지 함께 삭제(주의해서 사용!)
docker-compose down -v

# 사용하지 않는 네트워크와 이미지 등 dangling 리소스 정리
docker system prune

# 모든 이미지를 포함해 완전히 정리
docker system prune -a

# 캐시를 사용하지 않고 다시 빌드
docker-compose build --no-cache

# Docker의 디스크 사용량 확인
docker system df

저는 매주 금요일 퇴근 전에 docker system prune을 실행해 한 주 동안 쌓인 리소스를 정리합니다. 한 번은 Docker가 디스크 50GB를 사용하고 있었는데 정리 후 10GB로 줄었습니다.

예방 조치(문제가 생기기 전에 막기)

설정 검증:

# 시작하기 전에 설정 파일 검증
docker-compose config

이 명령은 YAML 구문을 확인하고 설정 오류를 찾아냅니다.

상태 검사:

services:
  web:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
      interval: 30s
      timeout: 10s
      retries: 3

healthcheck를 사용하면 서비스가 시작됐지만 실제로 정상 상태가 아닌 상황을 더 빨리 발견할 수 있습니다.

적절한 재시작 정책:

services:
  app:
    restart: unless-stopped  # 권장: 수동으로 중지하지 않는 한 항상 다시 시작
    # restart: always        # 항상 다시 시작
    # restart: on-failure    # 실패했을 때만 다시 시작

환경 변수 중앙 관리:

# .env 파일
DB_PASSWORD=your_password
API_KEY=your_key

# docker-compose.yml
services:
  app:
    environment:
      - DB_PASSWORD=${DB_PASSWORD}
      - API_KEY=${API_KEY}

이렇게 하면 YAML 파일을 직접 수정하지 않고도 설정을 바꿀 수 있어 팀 작업에도 편리합니다.

결론

처음 상황으로 돌아가 보겠습니다. 금요일 오후 3시 30분, 마감은 다가오는데 컨테이너가 시작되지 않습니다. 이제 무엇을 해야 하는지 알고 있습니다.

1. 당황하지 말고 심호흡합니다.
2. 오류 유형을 확인합니다(포트, 네트워크, 빌드, 종료, 권한).
3. 해당 절의 해결 방법을 간단한 것부터 차례로 시도합니다.
4. 그래도 해결되지 않으면 로그를 확인합니다. 답은 로그에 있습니다.

Docker Compose 오류 자체보다 더 큰 문제는 체계적인 점검 방법이 없는 것입니다. 이 5가지 오류 유형과 해결 순서를 기억하면 다음에는 5분 안에 문제를 해결할 수 있습니다.

마지막으로 팀 지식 베이스를 만들어 겪었던 문제와 해결 방법을 기록하세요. 저희 팀 Wiki에는 “Docker 자주 묻는 문제” 페이지가 있습니다. 신입 구성원이 읽으면 겪는 시행착오를 80% 줄일 수 있습니다.

여러분은 어떤 특이한 Docker Compose 오류를 겪어 봤나요? 댓글로 공유해 주세요. 다른 사람에게 도움이 될 수도 있습니다.