Failed to solve
The BuildKit compiler engine failed to compute the build steps (LLB definition) due to missing files, incorrect paths, or registry authorization errors.
Usually happens because:
- ☑ File to copy is missing from context
- ☑ Target file is excluded inside .dockerignore
- ☑ Base image repository access requires login credentials
🔍 Quick Checklist:
What is Failed to solve?
This error is thrown by Docker's modern BuildKit compiler engine when it encounters a failure while executing the low-level build definition (LLB) steps. Common triggers include COPY or ADD instructions pointing to local files that do not exist inside the active build context, referencing private images without login credentials, or encountering DNS lookup blocks inside the BuildKit container.
Common Causes
- Missing local files: Attempting to COPY a file or directory that is missing or excluded by .dockerignore.
- Registry authorization failure: Failing to authorize downloads for private base images defined in the FROM instruction.
- Syntax errors in multi-stage builds: Referencing incorrect stage aliases (e.g. COPY --from=builder-typo).
| Cause | Frequency |
|---|---|
| Missing COPY files or context mismatch | ⭐⭐⭐⭐⭐ |
| Registry pull authorization blocks | ⭐⭐⭐⭐ |
| Multi-stage alias naming typos | ⭐⭐⭐ |
Common Mistakes
- Using relative path dots (like `COPY ../parent-file.txt .`) that exit the active build context directory (Docker builds cannot access files outside the context root).
- Misspelling target image aliases inside multi-stage COPY operations.
How to Fix
Docker Operations & Verification
If a file is excluded inside .dockerignore, the COPY command will fail to locate it, triggering failed to solve.
# .dockerignore
node_modules
dist
# Fix: remove files that need to be copied into the container
# src/secrets.jsonPlatform Specific Fixes
Clearing local builder cache on Linux servers to resolve corrupted cache index paths.
docker builder prune -f
docker system prune --volumes -fBest Practices
- Verify the build context root parameter (the `.` at the end of the `docker build` command) points to the correct directory.
- Verify private registry logins exist inside runner scripts in CI/CD build environments.
Frequently Asked Questions (FAQ)
Q: What does failed to solve mean?
It is a generic error thrown by BuildKit when it cannot resolve the execution graph (LLB) of your build, usually due to missing files or registry blocks.
Q: How do I get more build log details?
Prepend the environment variable: 'BUILDKIT_PROGRESS=plain' to your build command (e.g., 'BUILDKIT_PROGRESS=plain docker build -t my-app .').
Q: Why does my COPY fail even if the file exists?
Check if the file or folder is listed inside your '.dockerignore' file. If excluded, BuildKit cannot see it.
Q: How do I disable BuildKit?
You can disable BuildKit by setting the environment variable 'DOCKER_BUILDKIT=0', but it is recommended to keep it enabled and fix the build structure.