failed-to-compute-cache-key Linux / DevOps

Docker Error: failed to compute cache key: not found — Исправление

Обновлено: 19.08.2026 · Официальная база знаний

Архитектура движка сборки BuildKit и контекст выполнения (Build Context)

Ошибка ERROR: failed to solve: failed to compute cache key: file not found генерируется современным движком сборки BuildKit (компонентом Moby/Docker) во время выполнения инструкций COPY или ADD в Dockerfile. Движок BuildKit создает ациклический граф зависимостей (DAG) и пытается вычислить контрольную сумму (хэш) входных файлов для кэширования слоев. Ошибка означает, что указанный в инструкции файл или каталог физически отсутствует внутри переданного контекста сборки (Build Context), либо был исключен правилами в файле .dockerignore.

Бизнес-риски:

Полная блокировка сборки релизных образов в CI/CD конвейерах, срыв автоматического тестирования веток разработки и увеличение Time-to-Market.

Таблица директив и причин сбоя BuildKit Cache Key

Инструкция Dockerfile	Типичный ошибочный путь	Причина отказа BuildKit
`COPY package.json ./`	`../package.json`	Попытка выйти за пределы корневого контекста сборки (нарушение изоляции).
`COPY src/ /app/src/`	`src/` (исключен в .dockerignore)	Файл заблокирован паттерном игнорирования и не попал в контекст сборки.
`COPY --from=builder /bin/app /`	`/bin/app` (в stage builder)	Предыдущий этап multi-stage сборки не сгенерировал файл по указанному пути.

Пошаговое исправление контекста сборки и правил игнорирования

Сценарий 1: Проверка правил в файле .dockerignore

Убедитесь, что требуемый файл или каталог случайно не заблокирован правилами исключений:

# Просмотр содержимого .dockerignore
cat .dockerignore

# Если нужно исключить все, кроме конкретной папки, используйте инверсию (!):
# *
# !src/
# !package.json

Сценарий 2: Коррекция корневого контекста сборки в CLI и Compose

Контекст сборки определяется последним аргументом команды docker build:

# Правильный запуск из корня репозитория с указанием пути к Dockerfile (-f):
docker build -t myapp -f docker/Dockerfile .

# В docker-compose.yml:
services:
  backend:
    build:
      context: . # Корень проекта
      dockerfile: deploy/Dockerfile

Сценарий 3: Сброс поврежденного кэша сборщика BuildKit

Если метаданные кэша BuildKit повредились на сборочном сервере:

# Очистка кэша сборщика BuildKit
docker builder prune -a -f

# Временное отключение BuildKit для проверки классическим сборщиком:
DOCKER_BUILDKIT=0 docker build -t myapp .

Типовые ошибки администраторов

Использование абсолютных путей хоста в COPY: Инструкция COPY /home/user/app /app не будет работать, так как пути в COPY всегда относительны корня build context.
Неучет регистра символов (Case Sensitivity): В Linux App.js и app.js — это разные файлы. На Windows/Mac сборка пройдет, но упадет в Linux-раннере CI/CD.

Сборки Docker образов в CI/CD регулярно падают или длятся слишком долго?
ITSTM оптимизирует Multi-stage Dockerfile, настроит удаленный кэш сборки (BuildKit cache-from) и ускорит ваши конвейеры в разы.

Практический опыт инженера: При организации Multi-Stage сборок сложных монорепозиториев всегда задавайте единый root context на верхнем уровне проекта. Это позволяет переиспользовать общие библиотеки и предотвращает ошибки cache key not found.

Частые вопросы (FAQ)

Почему сборка работает локально на Mac, но падает в GitLab CI?

macOS по умолчанию нечувствительна к регистру символов (case-insensitive), а Linux в CI строго различает регистр файлов и путей.

Можно ли в COPY скопировать файл, находящийся выше контекста сборки (../)?

Нет. По соображениям безопасности BuildKit запрещает выход за пределы переданного build context. Задайте родительский каталог как context.

Что делать, если ошибка возникает на шаге COPY --from=builder?

Проверьте предыдущий этап сборки. Убедитесь, что бинарник компилируется именно в тот каталог, откуда его забирает COPY.

Как проверить, какие файлы реально попадают в контекст сборки?

Запустите минимальный Dockerfile с 'FROM busybox' и 'COPY . /test' и проверьте содержимое через 'ls -la'.