[IT-정보] 컴포즈 파일 버전 오류 해결 – 원인별 진단 순서와 실무 해결법

왜 컴포즈 파일 버전 오류가 발생할까요

새벽에 갑자기 서버 배포 파이프라인이 멈췄다는 알림을 받으면 심장이 덜컥 내려앉곤 해요. 로그를 확인하니 “Unsupported config option”이나 “version is unsupported” 같은 메시지가 떠 있다면, 열에 아홉은 컴포즈 파일 버전 오류 해결이 시급한 상황이에요. 분명 로컬 개발 환경에서는 잘 돌아갔는데, 왜 운영 서버에만 올리면 이런 문제가 생기는 걸까요?

이런 문제는 단순히 오타 때문만은 아니에요. 사용하는 도커 엔진의 버전과 컴포즈 파일에 명시한 버전 규격이 서로 맞지 않거나, 최근 도입된 Compose Specification 방식에 익숙하지 않아서 발생하는 경우가 훨씬 많아요. 특히 도커 컴포즈가 V1에서 V2로 넘어가면서 명령어나 버전 처리 방식이 미묘하게 달라졌기 때문에, 운영 담당자 입장에서는 매우 혼란스러울 수밖에 없어요.

오늘 이 글을 끝까지 읽으시면 당황하지 않고 문제를 해결할 수 있는 능력을 갖추게 될 거예요. 단순히 에러를 고치는 법을 넘어, 왜 이런 에러가 발생하는지 근본적인 메커니즘을 이해하고 재발을 막는 환경을 구축하는 법까지 모두 다룰게요.

문제 진단 전 반드시 확인해야 할 체크리스트

본격적으로 에러 메시지를 분석하기 전에, 현재 우리가 서 있는 위치를 먼저 파악해야 해요. 무턱대고 파일을 수정하다가는 오히려 멀쩡하던 환경까지 꼬이게 만들 수 있거든요. 가장 먼저 확인해야 할 것은 현재 시스템에 설치된 도커 엔진과 컴포즈 CLI의 정확한 버전이에요.

많은 분이 실수하는 지점이 바로 여기예요. 로컬 PC에서는 최신 버전의 도커 데스크탑을 사용하면서, 서버에는 구버전의 리눅스 패키지를 그대로 방치하는 경우죠. 이 간극이 바로 컴포즈 파일 버전 오류 해결을 어렵게 만드는 주범이에요. 아래 표를 통해 현재 사용 중인 환경이 어떤 상태인지 비교해 보세요.

위 표를 보면 알 수 있듯이, V1과 V2는 완전히 다른 도구라고 봐도 무방해요. 만약 기존에 사용하던 docker-compose.yml 파일을 아무런 수정 없이 최신 서버로 가져갔다면, 명령어 체계부터 버전 해석 방식까지 어긋날 확률이 매우 높아요.

또한, YAML 문법의 엄격함도 미리 인지하고 있어야 해요. YAML은 들여쓰기(Indentation) 하나만 잘못되어도 전체 구조를 완전히 다르게 해석해 버려요. 버전 필드에 숫자를 적어야 할지, 따옴표를 붙인 문자열을 적어야 할지도 매우 민감한 문제입니다. 이러한 기초 지식이 준비되지 않은 상태에서는 에러 메시지가 나와도 무엇이 잘못되었는지 직관적으로 알기 어려워요.

오류 원인별 체계적인 진단과 실행 단계

이제 본격적으로 문제를 해결할 차례예요. 에러가 발생했을 때 가장 중요한 것은 추측이 아닌 데이터에 기반한 진단을 내리는 것이에요. 무작정 버전을 올리거나 파일을 지우는 대신, 아래 5단계 프로세스를 따라가 보세요.

STEP 1. 시스템 버전 정보 수집하기

가장 먼저 해야 할 일은 현재 환경의 Metadata를 확보하는 것이에요. 터미널을 열고 다음 두 명령어를 실행해서 결과를 기록해 두세요. 이 결과값은 나중에 구글링을 하거나 팀원에게 공유할 때 가장 결정적인 증거가 돼요.

• docker version: 도커 엔진 자체의 버전을 확인해요.
• docker compose version: 현재 사용 중인 컴포즈 도구의 버전을 확인해요.

만약 docker compose 명령어가 동작하지 않는다면 docker-compose --version을 시도해 보세요. 여기서 중요한 건 엔진 버전과 컴포즈 버전의 궁합이에요. 예를 들어 엔진은 20.10 버전인데 컴포즈는 최신 사양을 요구하는 파일을 읽으려 한다면, 반드시 호환성 에러가 발생하게 되어 있어요.

STEP 2. YAML 파일의 버전 선언 방식 검증하기

컴포즈 파일 최상단에 있는 version: '3.8' 부분을 유심히 살펴봐야 해요. 여기서 많은 실수가 발생하는데, 크게 두 가지 유형이 있어요.

첫 번째는 데이터 타입 오류예요. YAML에서 version: 3.8이라고 따옴표 없이 적으면, 파서(Parser)가 이를 숫자로 인식할 수 있어요. 하지만 컴포즈 스펙은 이 값을 문자열로 처리하기를 기대하는 경우가 많아요. 따라서 반드시 version: '3.8'처럼 따옴표를 붙여 문자열로 명시하는 것이 가장 안전해요.

두 번째는 버전 사양 불일치예요. 만약 파일에는 version: '3.9'라고 적혀 있는데, 서버의 도커 엔진이 구버전이라 3.9 사양의 기능을 지원하지 못한다면 “Unsupported config option” 에러를 뱉으며 실행을 거부해요. 이럴 때는 파일의 버전을 낮추거나 엔진을 업데이트해야 해요.

STEP 3. Compose Specification 적용 여부 판단하기

최근의 도커 환경은 Compose Specification이라는 새로운 표준을 따르고 있어요. 이 표준의 핵심은 더 이상 파일 상단에 version 필드를 강제로 적지 않아도 된다는 점이에요. 최신 V2 환경에서는 버전 필드가 없어도 도커가 알아서 가장 적절한 사양으로 해석하려고 노력해요.

하지만 여전히 많은 레거시 프로젝트가 버전 필드에 의존하고 있어요. 만약 최신 환경에서 버전 필드 때문에 계속 에러가 난다면, 차라리 해당 라인을 삭제하고 최신 사양에 맞게 설정을 재구성하는 것도 방법이에요. 단, 이 방식은 파일 내부에 사용된 특정 기능(예: deploy 설정)이 최신 사양과 호환되는지 확인한 후에 진행해야 해요.

STEP 4. 문법 구조와 들여쓰기 정밀 검사

에러 메시지가 mapping values are not set이나 could not find expected ':' 같은 식으로 나온다면, 이건 버전 문제가 아니라 순수한 YAML 문법 오류예요. 컴포즈 파일은 계층 구조가 생명이에요.

예를 들어, services 항목 아래에 서비스 이름이 와야 하고, 그 서비스 이름 아래에 image나 ports가 와야 해요. 이 계층이 한 칸이라도 어긋나면 컴포즈는 파일을 읽다가 길을 잃어버려요. 이런 경우에는 눈으로 찾는 것보다 YAML Linter 도구를 사용하는 것이 훨씬 빨라요. VS Code 같은 에디터를 사용 중이라면 YAML 확장을 설치해서 실시간으로 문법 오류를 잡아내는 습관을 들이는 것이 좋아요.

STEP 5. 실제 시나리오를 통한 문제 해결 적용

이해를 돕기 위해 실제 운영 환경에서 자주 발생하는 시나리오를 하나 구성해 볼게요. 개발자가 새로운 기능인 healthcheck 설정을 추가해서 파일을 업데이트했는데, 서버에서 배포가 실패했어요.

이처럼 문제를 발견하면 [에러 메시지 확인 → 관련 기능의 지원 버전 확인 → 파일 수정 또는 엔진 업데이트]라는 논리적인 순서를 유지해야 해요. 이 순서만 지켜도 엉뚱한 곳을 건드려 장애를 키우는 실수를 획기적으로 줄일 수 있어요.

자주 하는 실수와 해결법 및 FAQ

자주 하는 실수와 해결법

• ❌ 실수: 버전 필드에 따옴표 없이 숫만 입력함 (예: version: 3.8)
  → 왜 발생하는가: YAML 파서가 이를 부동 소수점 숫자로 인식해 형식이 깨짐
  → ✅ 해결법: version: '3.8'처럼 반드시 따옴표를 붙여 문자열로 선언하세요.
• ❌ 실수: 구버전 서버에서 최신 버전의 옵션을 사용함 (예: 3.8 버전용 옵션을 2.x 환경에서 사용)
  → 왜 발생하는가: 도커 엔진의 스펙 지원 범위가 파일의 요구사항보다 낮음
  → ✅ 해결법: 서버의 도커 엔진을 업데이트하거나, 파일의 버전을 낮은 사양으로 낮추세요.
• ❌ 실수: 들여쓰기를 탭(Tab) 문자로 사용함
  → 왜 발생하는가: YAML 표준은 탭 문자를 허용하지 않으며 공백(Space)만 허용함
  → ✅ 해결법: 에디터 설정에서 탭을 공백 2칸 혹은 4칸으로 자동 변환하도록 설정하세요.
• ❌ 실수: docker-compose와 docker compose를 혼용함
  → 왜 발생하는가: 설치된 환경이 V1인지 V2인지 정확히 모르는 상태에서 관습적으로 입력함
  → ✅ 해결법: docker compose version을 먼저 입력해보고, 동작하는 명령어를 하나로 통일하세요.
• ❌ 실수: 환경 변수 파일을 로드하지 못해 버전 인식 오류가 남
  → 왜 발생하는가: .env 파일 경로가 잘못되어 컴포즈가 설정을 제대로 읽지 못함
  → ✅ 해결법: docker compose --env-file .env up 처럼 경로를 명시적으로 지정해 보세요.

자주 묻는 질문

Q. Compose V2에서는 왜 version 필드를 안 써도 된다고 하는 건가요?

최신 도커 컴포즈는 특정 버전에 종속되는 방식이 아니라, 통합된 Compose Specification을 따르기 때문이에요. 즉, 파일에 버전을 적지 않으면 도커가 현재 엔진이 지원하는 가장 최신의 표준 사양을 자동으로 적용해요. 다만, 하위 호환성을 위해 명시적으로 적어주는 것도 여전히 유효한 방법이에요.

Q. 에러 메시지에 ‘Unsupported’가 뜨면 가장 먼저 뭘 확인해야 하나요?

가장 먼저 현재 사용 중인 도커 엔진의 버전을 확인해야 해요. 파일에 적힌 버전 사양을 엔진이 처리할 능력이 안 된다는 뜻이기 때문이죠. 엔진 업데이트가 어렵다면 컴포즈 파일의 버전을 낮추는 것이 가장 빠른 해결책이에요.

Q. YAML 문법이 완벽한데도 오류가 나면 어떻게 하나요?

그럴 때는 파일 내부의 특정 옵션 명칭을 의심해 보세요. 예를 들어, 예전에는 쓰던 옵션이 최신 버전에서 이름이 바뀌었거나 삭제되었을 수 있어요. 공식 문서에서 해당 옵션이 현재 스펙에 포함되어 있는지 꼭 확인해야 해요.

Q. 도커 데스크탑을 쓰는데 왜 서버와 환경이 다른가요?

도커 데스크탑은 컴포즈 V2가 기본으로 내장되고 엔진 업데이트도 매우 쉽지만, 리눅스 서버 환경은 OS 패키지 관리자(apt, yum 등)를 통해 직접 관리해야 하기 때문이에요. 서버 운영 시에는 반드시 버전 관리 정책을 세워야 해요.

Q. 버전 숫자를 ‘3’이라고만 적어도 되나요?
정해진 규칙은 없지만, 가급적 세밀한 버전(예: ‘3.8’)을 적는 것을 추천해요. ‘3’이라고만 적으면 엔진마다 해석하는 기준이 미묘하게 달라질 수 있어 예측 불가능한 동작을 유발할 수 있거든요.

안정적인 운영을 위한 마무리 단계

컴포즈 파일 버전 문제는 단순한 오타 문제가 아니라, 시스템의 구성 요소들이 서로 대화하는 방식이 어긋났을 때 발생하는 아주 논리적인 결과예요. 문제를 해결했다면, 다시는 같은 일로 밤을 지새우지 않도록 준비를 마쳐야 해요.

오늘 배운 내용을 바탕으로 지금 바로 실행해 보세요. 만약 현재 운영 중인 서버가 있다면, 다음 배포 전에 컴포즈 파일의 버전 선언 방식과 엔진 버전을 한 번 더 대조해 보는 것만으로도 큰 사고를 막을 수 있어요.

이번 주에는 팀원들과 함께 현재 사용하는 도커 이미지와 컴포즈 버전 리스트를 공유하여 표준 환경을 구축해 보는 것을 추천해요. 환경이 통일되면 트러블슈팅 시간은 획기적으로 줄어들 거예요.

같은 오류가 반복된다면 오늘 정리해 드린 진단 순서를 체크리스트로 만들어 두세요. 장애 대응의 속도가 달라질 거예요. 더 깊이 있는 컨테이너 운영 노하우가 궁금하다면 아래 글도 함께 읽어보시면 큰 도움이 될 거예요.

관련 글: 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드