Build failed: ADD failed 에러 해결법 – 원인 분석부터 완벽 해결까지

🚨 도입부

Docker를 사용하여 이미지를 빌드하는 과정에서 ‘Build failed: ADD failed’라는 에러 메시지를 마주쳤을 때의 좌절감을 이해합니다. 이 에러는 특히 프로젝트의 초기 단계에서 발생할 수 있으며, Dockerfile에서 ADD 명령어를 사용할 때 자주 발생합니다. 개발자들이 흔히 마주치는 몇 가지 시나리오로는, 파일 경로를 잘못 설정했거나, ADD 명령어를 쓸 때 파일이 존재하지 않을 때, 또는 소스 파일의 권한 문제가 있을 때 발생할 수 있습니다. 이 글에서 우리는 이 에러의 발생 원인을 철저히 분석하고, 단계별 해결 방법을 제공합니다. 이를 통해 예상 해결 시간은 약 30분에서 1시간 정도이며, 난이도는 중급 정도로 예상됩니다.

🔍 에러 메시지 상세 분석

‘Build failed: ADD failed’라는 메시지는 Dockerfile에서 ADD 명령어를 실행하는 동안 문제가 발생했음을 알립니다. 다양한 변형으로는 ‘ADD failed: no source files were specified’ 또는 ‘ADD failed: file not found’ 등이 있습니다. 이 에러는 주로 Dockerfile이 작성된 디렉토리에서 파일이나 디렉토리를 이미지에 복사할 때 발생합니다. 5가지 일반적인 상황은 다음과 같습니다:

• 파일 경로가 잘못 지정된 경우
• 복사하려는 파일이 존재하지 않을 때
• 파일 권한이 잘못 설정된 경우
• Docker daemon의 버전 문제가 있는 경우
• 네트워크 드라이브나 외부 디스크를 사용할 때

이 에러 메시지를 읽을 때 중요한 부분은 ‘ADD failed’ 후에 오는 구체적인 설명입니다. 초보자라면 이 부분을 통해 문제의 원인을 추측해볼 수 있습니다. 이와 비슷한 에러로는 ‘COPY failed’가 있으며, 두 에러는 같은 맥락에서 발생할 수 있습니다.

🧐 발생 원인 분석

먼저, 주요 원인 중 하나는 경로 설정의 오류입니다. Dockerfile에서 ADD 명령어를 사용할 때, 상대 경로와 절대 경로를 혼동할 수 있습니다. 예를 들어, 다음과 같이 잘못된 경로를 사용할 수 있습니다:

ADD /wrong/path/file.txt /app/

또한, 실제로 파일이 존재하지 않는 경우에도 발생합니다. 이럴 때는 ADD 명령어를 사용하기 전에 파일이 제대로 위치해 있는지 확인해야 합니다. 다음으로, 파일 권한 문제 때문에 발생할 수 있습니다. 특히 Linux 환경에서는 파일의 읽기 권한이 설정되어 있지 않으면 에러가 발생할 수 있습니다. 네 번째로, Docker의 구버전을 사용하고 있을 때 버그로 인해 발생할 수 있습니다. 마지막으로, 네트워크 드라이브나 외부 디스크를 사용할 때, 파일 시스템의 특성 때문에 문제가 발생할 수 있습니다. 각 원인의 확인 방법에는 파일 경로와 존재 여부 확인, 권한 설정 체크, Docker 버전 확인 등이 있습니다.

✅ 해결 방법

즉시 해결 가능한 방법으로는 다음 세 가지가 있습니다:

1. 파일 경로를 절대 경로로 설정해 보세요.

ADD /app/source/file.txt /app/

2. 파일의 존재 여부를 먼저 파일 시스템에서 확인하세요.
3. 파일 권한을 644로 설정하여 읽기 가능하도록 하세요.

chmod 644 /path/to/file.txt

표준 해결법으로는, Dockerfile에서 ADD 대신 COPY 명령어를 사용하는 것입니다. 이는 보안상 더 안전하고, 일반적으로 권장됩니다:

COPY source/file.txt /app/

또한, Docker 버전을 최신으로 업데이트하는 것도 중요한 해결책 중 하나입니다. 고급 해결방법으로는 네트워크 드라이브를 로컬로 마운트하여 사용하는 방법이 있습니다. 이는 파일 시스템의 호환성 문제를 해결할 수 있습니다. 각 해결 방법의 장단점과 사용 상황은 파일 경로의 절대적 명확성, 권한 설정의 필요성, Docker 버전의 최신 유지 등을 고려할 수 있습니다. 해결 후에는 Docker 이미지가 정상적으로 빌드되는지 확인해야 합니다.

🛡️ 예방법 및 베스트 프랙티스

이 에러가 재발하지 않도록 하려면, Dockerfile 작성 시 다음과 같은 체크리스트를 따르세요:

• 경로 설정은 항상 절대경로를 사용하세요.
• 파일의 존재 여부와 권한을 사전에 확인하세요.
• Docker 이미지를 빌드하기 전에 Dockerfile을 검토하고 테스트하세요.

추천 도구로는 Dockerfile Linter를 사용하여 Dockerfile을 검증할 수 있습니다. 팀 개발 시에는 코드 리뷰를 통해 Dockerfile의 문제를 사전에 발견하는 것이 좋습니다. 관련 문서화를 통해 각 Dockerfile의 목적과 사용법을 명시적으로 설명하세요.

🎯 마무리 및 추가 팁

이 글에서는 ‘Build failed: ADD failed’ 에러의 원인 분석과 해결 방법을 상세히 다루었습니다. 핵심 내용으로는 파일 경로 설정의 중요성, 권한 확인, Docker 버전 업데이트의 필요성을 들 수 있습니다. 비슷한 에러로는 ‘COPY failed’가 있으며, 관련 문제 해결 방법에 대한 추가 학습 리소스로는 Docker 공식 문서와 Stack Overflow 등을 추천합니다. 마지막으로, 이 에러를 극복하고 더 나은 개발자가 되기 위해 끊임없이 학습하고 성장하시길 응원합니다. 함께 이 문제를 해결해 나갑시다!