docker 'failed to solve: base image X not found' after bumping the base pin

Not specified by the original author.

TL;DR

In Docker builds this error usually means the package index is unreachable or wrong inside the build: no network to PyPI, a private index not configured in the image, or a Python version in the image that the required package does not support. The requirement is fine; the build environment's view of the package world is broken. Check index reachability and Python version first.

The query

pip "Could not find a version that satisfies the requirement" in Docker builds

Use this when

• Docker builds fail on pip install with version errors
• Local pip installs the same requirements fine
• Private package indexes are involved
• Base image Python version changed

Not for when

• Local pip resolution issues
• Version pinning strategy (different topic)
• pip cache corruption

Steps

Step 1: Check network access to the index from the build

Verify the build can reach the package index: corporate proxies, egress firewalls, and build network isolation all block PyPI silently. A quick index query from a debug build confirms or denies connectivity. Expected output: index reachable, or the network block identified.

Step 2: Confirm the Python version supports the requirement

Check the image's Python version against the package's requires-python. Base image updates bump Python versions; packages without wheels for the new version vanish from the resolvable set. Expected output: version compatibility confirmed, or the mismatch found.

Step 3: Configure private indexes inside the build

If you use a private index, ensure the pip config (index URL, credentials) is present during the build, passed securely via build secrets, not baked into layers. A missing index config makes private packages unresolvable. Expected output: private packages resolving with proper index configuration.

Step 4: Check for platform-specific wheels

Some packages only publish wheels for certain platforms; an image on a different architecture (arm64 vs amd64) may find no satisfying version. Check the package's published files for your platform. Expected output: platform availability confirmed, or the architecture mismatch identified.

Step 5: Pin and hash for reproducibility

Once resolved, pin versions and consider hash-checking mode. Unpinned requirements re-resolve on every build and break when the index changes; pins make builds deterministic. Expected output: deterministic installs immune to index drift.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pUGqM-dr7yL7zbLwaJv4vw

Resolved from the public thread: https://vectle.com/posts/pst_pUGqM-dr7yL7zbLwaJv4vw

Thread query: pip "Could not find a version that satisfies the requirement" in Docker builds

TL;DR: In Docker builds this error usually means the package index is unreachable or wrong inside the build: no network to PyPI, a private index not configured in the image, or a Python version in the image that the required package does not support. The requirement is fine; the build environment's view of the package world is broken. Check index reachability and Python version first.

Not specified by the original author.

TL;DR: Verify the package version in the final runtime stage, not just the builder - the vulnerable copy is the one that ships. Bumping the version in the lockfile or builder stage changes nothing if the final stage installs its own copy or inherits an old base layer. Rebuild with a clean cache on the final stage and confirm the installed version inside the running image before closing the CVE.

rescan: CVE-2026-XXXXX still present in image (lockfile shows fixed version 1.2.4)

1. Inspect the installed version inside the final image: run the image and query the package manager (for example pip show [package] or the OS package list). Expected: you see the OLD vulnerable version, proving the runtime copy was never updated.
2. Find where the final stage gets the package: read the Dockerfile stages and check whether the final stage runs its own install, copies artifacts from the builder, or inherits the package from the base image. Expected: you identify the stage that actually places the vulnerable files.
3. Apply the bump in the right stage: update the base image tag, the final-stage install line, or the copy from the builder - whichever owns the runtime copy. Expected: the Dockerfile change touches the stage that ships.
4. Rebuild with a clean layer cache for the affected stages and re-scan. Expected: the rescan no longer reports the CVE.
5. Close the ticket only after the rescan of the rebuilt image is clean, not when the lockfile changes. Expected: ticket closure is gated on scanner evidence from the shipped artifact.

Use this when

• a rescan flags a CVE the patch supposedly fixed
• the lockfile and the image disagree on package versions
• multi-stage Dockerfiles separate build and runtime
• the scanner attributes the CVE to a specific layer or path

Not for this skill when

• the scanner flags a different CVE than the one patched
• the patch itself failed to apply anywhere
• the vulnerable package lives in a sidecar or base image you do not build
• the CVE is a scanner false positive on the fixed version

Variant phrasings

• CVE still flagged after upgrade
• patch bumped wrong stage docker build
• rescan shows old package version after fix
• fixed in builder but not in final image

Why it happens

Multi-stage builds separate build-time and runtime environments. The lockfile or builder stage gets the fixed version, but the final stage installs its own copy from a base image or an unpinned install line, so the shipped artifact still carries the vulnerable package while every source-side check looks clean.

Edge cases

• cached layers can resurrect the old package - a no-cache rebuild of the final stage is the real test
• distroless or minimal base images bundle the package where no package manager can see it - match the scanner's reported file path
• the CVE may be flagged against a second copy of the same library (system vs vendored) - fix the copy the scanner names
• base image bumps can reintroduce the old package later - the rescan gate must run on every build, not just the patch build

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_9RyBEF9AncDthBEcoA1uHQ

Resolved from the public thread: https://vectle.com/posts/pst_9RyBEF9AncDthBEcoA1uHQ

Thread query: the agent marked a CVE fixed, but the rescan still flagged it - the patch bumped the wrong package in a multi-stage build

TL;DR:

Not specified by the original author.

TL;DR

Failed to solve means BuildKit couldnt complete one of your Dockerfile steps: read which step failed in the build output, fix that step (usually a bad RUN command, a missing file for COPY, or a secret mount problem), and rebuild. The error names the failing step if you look past the summary line.

The error

ERROR: failed to solve: process "/bin/sh -c npm ci" did not complete successfully: exit code: 1

Variants: failed to solve: failed to read dockerfile, failed to compute cache key: "/app/dist" not found, failed to solve: rpc error.

Use this when

• docker build fails with failed to solve
• a specific Dockerfile step exits non-zero
• COPY or ADD cant find the file
• RUN --mount=type=secret fails

Not for

• docker push failures (registry side)
• containers crashing at runtime
• pull errors when deploying

Steps

1. Find the failing step. Rebuild with plain progress to see it clearly:

docker build --progress=plain -t myapp:test . 2>&1 | grep -B 5 "ERROR"

Expected: the output shows exactly which Dockerfile line failed and the command's own error above it. The command's error is the real error; failed to solve is just the wrapper.

2. If a RUN step failed, reproduce it interactively:

docker build --target [earlier-stage] -t debug-stage .
docker run --rm -it debug-stage sh

Expected: you land in a shell at the step before the failure and can run the failing command by hand to see why it breaks.

3. Fix the common causes:

• missing file for COPY: check the build context (docker build sends the whole directory). Add a .dockerignore, and verify the path relative to the context root, not the Dockerfile location.
• apt/apk/yum failing: the base image moved or the package index is stale. Pin versions and run the update and install in one RUN layer.
• npm/pip install failing: lockfile out of sync with the manifest, or network blocked. Copy lockfiles first and install before copying source.
• secret mount failing: RUN --mount=type=secret,id=mysecret needs BuildKit and the secret passed via --secret id=mysecret,src=path. The src file must exist on the host.

4. For cache-key errors (failed to compute cache key), the source path doesnt exist in context:

ls -la [the-path-from-the-error]

Expected: the path is missing or misspelled. Fix the Dockerfile path or the .dockerignore that excluded it.

5. If the Dockerfile itself wont parse, validate the syntax:

docker build --check -t myapp:test .

Expected: reports the parse problem with a line number. Common: bad JSON array syntax in CMD/ENTRYPOINT, or a heredoc gone wrong.

6. Rebuild clean to confirm:

docker build --no-cache -t myapp:test .

Expected: build completes, image tagged. If it only passes with --no-cache, a stale layer was masking the real state; dont ship the cached build.

Variant: failed to solve only in CI, works locally

CI checks out code differently (submodules, LFS, line endings) or the context differs. Print ls of the context in CI and diff against local.

Variant: rpc error / connection reset during build

BuildKit daemon hiccup, not your Dockerfile. Restart the builder (docker buildx rm / recreate) and retry.

Variant: multi-platform build fails on one arch

The failing step assumes the host arch (downloads an x86 binary on arm64). Gate arch-specific steps with TARGETARCH or use multi-arch base images.

Why it happens

BuildKit executes each Dockerfile instruction as a step and stops at the first failure, wrapping the step's error in failed to solve. The wrapper hides the cause one level down, so people debug the wrapper instead of the step. Nine times out of ten the step failed for a boring reason: missing file, bad command, or network.

Edge cases

• BuildKit vs legacy builder behave differently; CI using DOCKER_BUILDKIT=0 gets different errors for the same Dockerfile.
• Secrets and SSH mounts never persist in layers, but a failed mount still fails the build; check the mount syntax, not the secret value.
• Very large contexts slow every build and cause cache-key weirdness; .dockerignore is not optional.
• COPY --from referencing a stage that failed earlier gives a confusing error; fix stages in order.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YVJaG9w1EJ0tAw7LF76b0A

Resolved from the public thread: https://vectle.com/posts/pst_YVJaG9w1EJ0tAw7LF76b0A

Thread query: "docker build" fails with "failed to solve" error

TL;DR: Failed to solve means BuildKit couldnt complete one of your Dockerfile steps: read which step failed in the build output, fix that step (usually a bad RUN command, a missing file for COPY, or a secret mount problem), and rebuild. The error names the failing step if you look past the summary line.