Docker Compose: yaml: line N: mapping values are not allowed in this context

#Что означает ошибка

Ошибки YAML в docker-compose.yml (yaml: line N: did not find expected key, mapping values are not allowed here, found character that cannot start any token) почти всегда вызваны отступами, табуляцией или специальными символами в значениях.

YAML чувствителен к пробелам: структура задаётся количеством пробелов, а табуляция запрещена.

Проверка конфигурации выполняется встроенной командой.

Ошибка синтаксиса YAML: в файле неверные отступы, табуляция вместо пробелов, пропущено двоеточие или пробел после него. YAML чувствителен к отступам.

#Причины и решения

#Пошаговое решение

1. Запустите docker compose configОткройте терминал в папке, где находится compose.yaml, compose.yml или docker-compose.yml, и выполните docker compose config --quiet. Эта проверка синтаксиса не запускает контейнеры и укажет на ошибку разбора с номером строки (он может относиться и к соседней строке выше). Затем откройте файл в редакторе с отображением номеров строк, например VS Code → «Файл» → «Открыть файл». Команда docker compose config без --quiet может показать секреты, не публикуйте вывод.
2. Проверьте отступыОколо указанной строки посмотрите структуру YAML: вложенность задаётся пробелами, обычно удобно использовать два пробела на уровень; символы табуляции для отступов не применяйте. В редакторе VS Code включите «Вид» → «Внешний вид» → «Отображать пробелы» в настройках, если нужно видеть скрытые символы. Исправьте только место ошибки, сохраните файл и ещё раз выполните docker compose config --quiet.
3. Заключите спорные значения в кавычкиЕсли значение в YAML содержит двоеточие с пробелом, # или другие специальные символы, заключите именно значение в кавычки. Для записи порта используйте ports: - "8080:80" с правильными отступами; кавычки помогают избежать неожиданных преобразований числа или двоеточия. Не помещайте в кавычки весь блок YAML целиком. Проверьте исправление командой docker compose config --quiet.
4. Запустите yamllintПри сложном файле установите расширение YAML для редактора или используйте проверку yamllint в отдельной среде разработчика (если инструмент установлен). Сверьте подсказки с синтаксисом Docker Compose, поскольку обычная проверка YAML не знает всех правил Compose. Не загружайте рабочие файлы с паролями на сторонние онлайн-валидаторы: они могут сохранять содержимое.
5. Проверьте переменные окруженияОткройте .env рядом с файлом Compose (если используется) и проверьте, что нужные переменные действительно заданы, а пути и порты корректны. Для передачи символа $ в команду внутри файла Compose может потребоваться $$, но это относится к правилам подстановки Compose, а не к обычному YAML. После правок выполните docker compose config --quiet, затем docker compose up -d только если проверка прошла и изменение развёртывания согласовано.
6. Не выводит развёрнутую конфигурацию с возможными секретами

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Не выводит развёрнутую конфигурацию с возможными секретами

   # В каталоге с файлом Compose — только проверка, без запуска

   docker compose config --quiet

#Проверка

Выполните docker compose config — команда проверит синтаксис и выведет итоговую конфигурацию с подставленными переменными. Номер строки в сообщении указывает на место ошибки или строку после неё. Используйте редактор с отображением пробелов (VS Code, плагин YAML) и линтер: yamllint docker-compose.yml. Онлайн-проверка: yamllint.com.

#Частые ошибки

Табуляция вместо пробелов; смешанные отступы (2 и 4 пробела) в одном блоке; пропущенный пробел после двоеточия (image:nginx); двоеточие в значении без кавычек (command: echo a: b); значения yes, no, on интерпретируются как булевы; порты вида 80:80 лучше брать в кавычки ("80:80"); неверное расположение ключа (например, volumes внутри ports); отсутствие services:.

#Версии и переменные

Ключ version: в Compose V2 необязателен и выдаёт предупреждение; проверьте установленную версию docker compose version. Переменные ${VAR} берутся из .env и окружения; значение по умолчанию: ${VAR:-default}. Знак $ внутри значений экранируйте как $$. Для длинных строк используйте > или |. Сравните свой файл с примерами на docs.docker.com.