Docker ERROR: failed to solve / Dockerfile syntax error の原因と解決方法

ERROR: failed to solve: process … did not complete successfully とは

Dockerで「ERROR: failed to solve」はイメージのビルド時に最も頻繁に遭遇するエラーです。Dockerfileの命令の実行に失敗した場合、パッケージのインストールエラー、ファイルのコピー失敗など、様々な原因で発生します。Docker初学者が最初につまずくエラーの代表格です。

エラーの発生パターン

このエラーは主に以下のようなケースで発生します。

パターン1: パッケージインストールの失敗

FROM ubuntu:22.04
RUN apt-get install -y curl
# E: Unable to locate package curl
# ERROR: process "/bin/sh -c apt-get install -y curl" did not complete successfully

パッケージリストが更新されていない状態でapt-get installを実行すると、パッケージが見つからずエラーになります。Dockerイメージのベースには最新のパッケージリストが含まれていないため、必ずapt-get updateを先に実行する必要があります。

FROM ubuntu:22.04
# apt-get update を先に実行し、同じRUN命令で結合する
RUN apt-get update && apt-get install -y curl \
    && rm -rf /var/lib/apt/lists/*

パターン2: COPYするファイルが存在しない

FROM node:18
WORKDIR /app
COPY package.json .
# ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref
# "/package.json" not found

ビルドコンテキスト内にpackage.jsonが存在しないか、.dockerignoreで除外されているためエラーになります。

# 修正: ビルドコンテキストにファイルがあることを確認
# .dockerignore に package.json が含まれていないかチェック

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

パターン3: ベースイメージやタグの指定ミス

FROM node:latset
# ERROR: pull access denied, repository does not exist
# or may require authorization

イメージ名やタグのスペルミス（latset→latest）により、Docker Hubからイメージをプルできずエラーになります。

# 修正: 正しいイメージ名とタグを指定
FROM node:latest
# または特定バージョンを固定（推奨）
FROM node:18-alpine

根本原因の特定方法

エラーメッセージの直前に表示されるビルドステップの出力を確認します。「Step X/Y」の番号で、Dockerfileのどの命令で失敗したかを特定できます。問題のRUN命令を分割して、どのコマンドで失敗しているかを切り分けると効率的です。

# デバッグ方法: 失敗する手前の段階でシェルに入る
# 方法1: 問題のRUNを一時的にコメントアウトしてビルド
# 方法2: docker run -it <途中のイメージ> /bin/bash で中間コンテナに入る

# ビルドログを詳細に表示
docker build --progress=plain --no-cache -t myapp .

防止策とベストプラクティス

Dockerfileのベストプラクティスに従うことでビルドエラーを減らせます。RUN命令はなるべく結合し、apt-get updateとinstallは同じレイヤーで実行します。マルチステージビルドを活用し、最終イメージを軽量に保ちましょう。

# ベストプラクティス例
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# 本番用の軽量イメージ
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

Stack Overflowでの質問状況

Stack Overflowでは、Bashに関する質問が約140,495件投稿されており、ERROR: failed to solve: process … did not complete successfullyは最も頻繁に質問されるエラーカテゴリの一つです。

よくある質問（FAQ）