docs: add troubleshooting for okteto up image pull EOF failure#1269
Open
ekline[bot] wants to merge 5 commits into
Open
docs: add troubleshooting for okteto up image pull EOF failure#1269ekline[bot] wants to merge 5 commits into
ekline[bot] wants to merge 5 commits into
Conversation
ekline[bot] <202747777+ekline[bot]@users.noreply.github.com> Signed-off-by: ekline[bot] <202747777+ekline[bot]@users.noreply.github.com>
ekline
Bot
requested review from
codyjlandstrom,
ifbyol,
pchico83 and
rlamana
as code owners
✅ Deploy Preview for okteto-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
The original entry framed the EOF pull failure as a transient CDN issue to retry. The real cause is a cluster egress allowlist that doesn't include the host in the error: Docker added the CDN domain production.cloudfront.docker.com (May 2026), and allowlists scoped to the registry and an older CDN start dropping layer downloads while the manifest still resolves. Lead with that cause, drop the rate-limit guidance (a distinct 429 failure), and trim the entry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Cody Landstrom <cody@okteto.com>
ifbyol
reviewed
Jun 24, 2026
|
|
||
| ## Pulling the development image fails with an `EOF` error | ||
|
|
||
| The image pull runs on the Kubernetes node, not on your machine. When the node can't finish downloading the image from Docker Hub, `okteto up` relays the node's error and exits: |
Member
There was a problem hiding this comment.
This still mentions okteto up. I don't know if we want to leave it, but it sounds odd that we mention the problem is in the cluster side, but we only mention okteto up (or if that happens during an okteto up).
I would try to make it generic.
Contributor
There was a problem hiding this comment.
Tried to make it more generic while leaving okteto up as the example
| Failed to pull image "node:25-alpine3.22": failed to pull and unpack image "docker.io/library/node:25-alpine3.22": failed to copy: httpReadSeeker: failed open: failed to do request: Get "https://production.cloudfront.docker.com/...": EOF | ||
| ``` | ||
|
|
||
| The `EOF` means the connection to the host in the error closed before the image layer finished downloading. The usual cause is an egress policy on the cluster — a firewall, proxy, or domain allowlist — that doesn't permit that host. Pulling from Docker Hub is a two-stage flow: the node authenticates against `auth.docker.io` and reads the manifest from `registry-1.docker.io`, then follows a redirect to a CDN host to download each layer. Docker changes its CDN domains over time — it added `production.cloudfront.docker.com` in May 2026 — so an allowlist that only covers the registry and an older CDN starts failing on layer downloads while the manifest still resolves. |
Member
There was a problem hiding this comment.
It seems this is only focused to DockerHub issues, but this error could happen with any registry.
I don't knot if we want to make it generic to other scenarios/registries, but if we don't, maybe we should change the title Pulling the development image fails with an EOF error to reflect that this only talks about DockerHub.
Contributor
There was a problem hiding this comment.
Yes good call. Changed this up and pulled out docker hub as a "common example"
Let me know what you think
Co-authored-by: Ignacio Fuertes <nacho@okteto.com>
Address review feedback from @ifbyol: - Frame the failure generically: image pulls run on the node for any pod, so the EOF is not specific to okteto up. okteto up is now shown only as where the example error surfaces. - Generalize the cause to any registry that redirects layer downloads to a separate CDN/storage host, with Docker Hub kept as the concrete example rather than the sole scope. Title was already updated to "Pulling an image fails with an EOF error". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Cody Landstrom <cody@okteto.com>
ifbyol
approved these changes
Jun 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this documents
Adds a troubleshooting entry to the Known Issues reference page for an
okteto upfailure where activating the Development Container fails while the base image is pulled, with afailed to pull and unpack image "docker.io/library/node:25-alpine3.22" ... cloudfront.docker.com ...: EOFerror.Why
A customer hit this error on
okteto up(CLI3.19.0). The entry explains the cause and gives actionable remediation steps, keyed on the error text so it surfaces in search.What it says
EOFis a node-to-Docker Hub CDN connection issue; common causes are dropped or throttled connections, Docker Hub anonymous pull rate limits, and proxy/firewall/TLS inspection.okteto up, inspect pod events, configure Docker Hub credentials via Registry Credentials, allow egress to Docker Hub hosts, or host the image in the Okteto Registry and reference it via the manifestimagefield.How to verify
cmd/up/activate.gorelays node pod-event messages; pull failures are not auto-retried) and the platform Registry Credentials webhook.📝 Created with EkLine · View session