Docker Compose ‘found character that cannot start any token’ 해결

Docker Compose를 사용하여 서비스를 빌드하여 실행하기 위해 docker compose up 명령어를 사용합니다.

$ docker compose up -d --build my-server

이 때 아래와 같이 에러 메시지가 발생하는 경우가 있습니다.

parsing /srv/www/docker-compose.yml: yaml: line 23: found character that cannot start any token

이 문제는 Docker Compose에서 참조하는 설정 파일인 docker-compose.yml (파일 이름은 다를 수 있음) 파일을 읽는(파싱하는) 과정에 문제가 발생하여 정상적으로 빌드하지 못해 발생하는 문제입니다. (여기서 설정 파일의 파일 확장자는 .yml일 수도 있고 .yaml일 수도 있습니다.)

이에 대한 해결 방법은 간단합니다. 에러 메시지에서 가리키는 파일을 vim이나 기타 다른 텍스트 편집기로 열어 문제가 생긴 줄(line)로 이동합니다.

그렇다면 해당 줄에서 어떤 문제가 발생하였기에 Docker Compose가 파싱에 실패한 것일까요?

일반적으로 Compose 설정 파일에서 사용하지 못하는 특수문자가 사용되었거나, .yml 확장자의 파일에서 잘못된 규칙으로 구성되었을 경우에 발생합니다.

그 중에서 가장 많이 하는 실수 중 하나는 들여쓰기를 할 때 스페이스(공백) 대신 탭(TAB) 기호를 사용하는 것입니다. yml 또는 yaml 파일에서는 들여쓰기에 탭 기호를 사용하지 않고 공백 두개로 구분을 합니다. 이외에는 yml의 스펙에 따라 사용 가능한 특수문자를 사용해야 합니다.

모든 문제를 수정한 후 다시 빌드를 시도해보면 정상적으로 서비스가 빌드 및 실행 되는 것을 확인할 수 있습니다.